Požadavek send-request

Účel a dopady

Odešle (typicky HTTP) požadavek jinému serveru a vrátí jeho odpověď zabalenou v odpovědi send-request – funguje jako proxy k libovolné externí (nejčastěji HTTP) službě. Požadavek sám o sobě nic nemění v databázi; jeho účinky jsou vždy na straně cílového serveru.

Dostupnost, kontext, oprávnění apod.

• Dostupné každému přihlášenému uživateli bez zvláštního oprávnění.
• Zpracování send-request je vždy provedeno bez ohledu na stav obálkové transakce. I uvnitř odvolané/přeskočené transakce se tedy odchozí HTTP volání provede.
• Atribut debug="true" se v produkčním sestavení uplatní jen tehdy, má-li volající r_admin nebo je session impersonovaná administrátorem; ve vývojovém sestavení se uplatní bez omezení.
• Atributy cert-chain/cert-key (cesta ke klientskému certifikátu) fungují jen je-li na serveru nastavena cesta k úložišti certifikátů; zadaná cesta je vždy ověřena, že nevede mimo tento kořenový adresář („jail“ kontrola) – jinak požadavek skončí obecnou chybou parametrů.

XML požadavek (syntax + popis)

  <request>
   <send-request
    url="{string}"
    post="{string}"
    content-type="{string}"
    preserve-headers="{bool}"
    preserve-cookies="{bool}"
    output="{string}"
    authentication="{string}"
    profile="{string}"
    scope="{string}"
    user-name="{string}"
    password="{string}"
    bearer="{string}"
    cert-chain="{string}"
    cert-key="{string}"
    timeout="{number}"
    size-limit="{number}"
    accepted-state="{number}"
    http-method="{string}"
    http-header...="{string}"
    id="{string}"
    url-translate="{string}"
    debug="{bool}"
    source="{string}"
    shared-objects="{bool}"
    >
    {string}
   </send-request>
  </request>

Parametry a pravidla (atributy, potomci)

• url - Cílové URL - Adresa, na kterou se požadavek odešle; XML entity se před odesláním dekódují. (typ: string; nepovinný – bez něj požadavek nemá cíl)
• post - Kódování vstupních dat - Určuje, jak se má sestavit tělo POST požadavku z obsahu elementu send-request. (typ: enum; nepovinný; výchozí: chování jako u neznámé hodnoty, viz níže; povolené rozpoznávané hodnoty: hex, base64, xml, xml-replace, json; jakákoli jiná hodnota, včetně plain, nebo chybějící atribut vede k výchozímu chování „syrový vnitřek elementu“ popsanému v sekci Zpracování)
• content-type - Content-Type požadavku - Hlavička zaslaná cílovému serveru. (typ: string; nepovinný; není-li uveden a post="json" byl úspěšně zpracován, použije se application/json; jinak se nepřidává explicitní hodnota a použije se výchozí chování serveru)
• preserve-headers - Přenos hlaviček klienta - Přenese hlavičky z klienta na cílový server (bezpečnostní hlavičky se nepřenášejí). (typ: bool; nepovinný; výchozí: false)
• preserve-cookies - Přenos cookies - Přenese cookies mezi klientem a cílovým serverem. (typ: bool; nepovinný; výchozí: false)
• output - Kódování výstupních dat - Určuje, jak se má zpracovat přijatá odpověď. (typ: enum; nepovinný; výchozí: chování jako u neznámé hodnoty/auto, viz níže; povolené rozpoznávané hodnoty: hex, xml, json, csv, txt, base64, raw, file, temp; hodnota auto, jakákoli jiná neznámá hodnota nebo chybějící atribut vedou ke stejnému výchozímu chování – způsob zpracování pak určí content-type přijaté odpovědi)
• authentication - Způsob autentizace - (typ: enum; nepovinný; výchozí: bez autentizace; povolené hodnoty: server, oauth, client, bearer; jiná hodnota se tiše chová jako neuvedená)
• profile - Serverový profil - Vyžadován při authentication="server" nebo authentication="oauth"; bez něj požadavek skončí obecnou chybou parametrů. (typ: string; podmíněně povinný)
• scope - OAuth scope - Použije se jen při authentication="oauth". (typ: string; nepovinný)
• user-name - Uživatelské jméno - Použije se jen při authentication="client". (typ: string; nepovinný)
• password - Heslo - Použije se jen při authentication="client". (typ: string; nepovinný)
• bearer - Bearer token - Použije se jen při authentication="bearer". (typ: string; nepovinný)
• cert-chain - Cesta ke klientskému certifikátu - Relativní k serverové konfiguraci certPath; musí zůstat uvnitř tohoto kořenového adresáře. (typ: string; nepovinný; vyžaduje současně platný cert-key, jinak požadavek skončí obecnou chybou parametrů)
• cert-key - Cesta ke klíči klientského certifikátu - Stejná pravidla jako cert-chain. (typ: string; nepovinný)
• timeout - Časový limit v ms - (typ: number; nepovinný; při neuvedení použije server výchozí časový limit; neplatná hodnota vede k obecné chybě parametrů)
• size-limit - Maximální velikost odpovědi v bajtech - (typ: number; nepovinný; neplatná hodnota vede k obecné chybě parametrů)
• accepted-state - Očekávaný HTTP stavový kód - Liší-li se skutečný stav od zadaného, požadavek je vyhodnocen jako neúspěšný. (typ: number; nepovinný; bez atributu je úspěšná jakákoli přijatá odpověď)
• http-method - HTTP metoda - Libovolný řetězec; bez uvedení server volí GET nebo POST podle přítomnosti těla. (typ: string; nepovinný)
• http-header... - Vlastní HTTP hlavička - Libovolný atribut, jehož název začíná (bez ohledu na velikost písmen) na http-header, se s neprázdnou hodnotou vloží jako samostatná HTTP hlavička (lze tedy uvést i vícekrát pod různými sufixy, např. http-header-1, http-headerFoo). (typ: string; nepovinný, opakovatelný)
• id - Identifikátor požadavku - Echoem vrácen v odpovědi, byl-li uveden. (typ: string; nepovinný)
• url-translate - Kódování části URL za ? - Uplatní se jen pokud url obsahuje ? a hodnota není "false". (typ: enum; nepovinný; výchozí: false, tedy žádné kódování; povolené hodnoty: true/min (shodná množina nekódovaných znaků), plus, fn, alnum, all, nebo libovolný uživatelsky definovaný řetězec povolených znaků)
• debug - Ladicí režim - Viz omezení oprávnění v sekci Dostupnost výše. (typ: bool; nepovinný; výchozí: false)
• source - Zdrojová IP/adresa odchozího požadavku - (typ: string; nepovinný; speciální hodnoty [hostname] a [ip] vyžadují, aby požadavek přišel z reálného webového/soketového spojení, jinak skončí chybou „Preddefinovany atribut...“; jakákoli jiná hodnota se použije doslovně jako zdrojová adresa)
• shared-objects - Sdílení CURL spojení - (typ: bool; nepovinný)

Potomek: volitelný obsah elementu (text, jeden vnořený element, nebo posloupnost flexideo dokumentových uzlů) – jeho zpracování určuje atribut post, viz „Zpracování a vedlejší účinky“.

Ověřené nesrovnalosti oproti starší dokumentaci

• Starší dokumentace uváděla atributy preserved-headers/preserved-cookies. Platné atributy jsou preserve-headers/preserve-cookies (bez „d“).
• Starší dokumentace u output/post neuváděla hodnoty file/temp (výstup) a neuváděla atributy cert-chain/cert-key, scope, shared-objects vůbec.
• Starší dokumentace u source chybně uváděla jako jeho možné hodnoty i http-method a id – to jsou samostatné, nesouvisející atributy; ve skutečnosti source rozpoznává jen [hostname]/[ip], jinak bere hodnotu doslovně.
• Starší dokumentace tvrdila výchozí content-type text/xml. Taková výchozí hodnota nastavena není (viz popis atributu content-type výše); toto tvrzení bylo odstraněno jako neověřené.

Příklady požadavku

(Zatím bez ověřeného příkladu; viz příklad do-request.)

Zpracování a vedlejší účinky

• Sestavení těla POST podle post:
  • hex/base64: V praxi post="hex" a post="base64" u tohoto požadavku vždy vedou k chybě „Nerozpoznany parametr“, bez ohledu na obsah těla.
  • xml/xml-replace: do těla se vloží serializovaný první potomek elementu (xml-replace navíc nahradí #>## za >).
  • json: obsah elementu se převede z flexideo XML na JSON; při neúspěchu převodu požadavek skončí chybou „Nerozpoznany parametr“. Při úspěchu se automaticky nastaví content-type: application/json, není-li content-type uveden výslovně.
  • Jakákoli jiná/chybějící hodnota (včetně plain): tělo požadavku je syrový vnitřní XML text elementu send-request (bez jeho vlastní otevírací/zavírací značky), beze změny kódování.
• url-translate: kóduje jen část URL za prvním ?; bez ? v url nemá zadaný url-translate žádný viditelný efekt, i když je uveden.
• Výsledek volání: server provede HTTP volání. Uspěje-li, sestaví odpověď type="ok"; tvar jejího těla závisí na output a skutečném content-type přijaté odpovědi.
  • Zvláštní případ: selže-li až samotné zapsání nebo zpracování přijaté odpovědi poté, co již začala úspěšná odpověď, server ji dodatečně přepíše na type="error" s prázdným detail="" a doplní http-state. Transakční obálka tento stav nemusí vyhodnotit stejně jako ostatní chyby tohoto požadavku.
• debug="true" (při úspěšném volání): do odpovědi se navíc vloží uzel <fxd:debug xmlns:fxd="http://www.flexideo.com/actions/debug"> obsahující text *** Request *** s odeslaným požadavkem a *** Response *** se syrovou přijatou odpovědí.

XML odpověď (syntax + popis)

  <response>
   <send-request
    type="ok|error"
    id="{string}"
    http-state="{number}"
    detail="{string}"
    >
    <fxd:debug xmlns:fxd="http://www.flexideo.com/actions/debug"> ... </fxd:debug> ?
    {string}
   </send-request>
  </response>

Parametry a pravidla (atributy, potomci) – odpověď

• type - Výsledek - "ok" nebo "error". (typ: enum; povolené hodnoty: ok, error)
• id - Identifikátor - Echem vrácená hodnota id z požadavku, byla-li uvedena. (typ: string)
• http-state - HTTP stavový kód - Přítomen, byl-li přijat od cílového serveru (chybí u chyb vzniklých ještě před odesláním). (typ: number)
• detail - Popis chyby - Přítomen jen v chybové odpovědi. (typ: string)

Obsahem úspěšné odpovědi je tělo zpracované podle output (viz „Zpracování“) a případně vnořený <fxd:debug> uzel při debug="true".

Příklady odpovědi

(Zatím bez ověřeného příkladu; viz příklad do-request.)

Chyby a reakce

• <send-request type="error" detail="Nerozpoznany parametr"> + vnořené diagnostické uzly error + </send-request> – selhal parsing některého vstupního atributu: timeout/size-limit/accepted-state (neplatné číslo), post (viz větev hex/base64 výše, nebo neúspěšný převod na JSON), authentication="server"/"oauth" bez profile, nebo neplatná/nejailovaná cesta cert-chain/cert-key.
• <send-request type="error" detail="Preddefinovany atribut ([]) lze pouzit pouze u pozadavku zadaneho z weboveho rozhrani"> + vnořené diagnostické uzly error + </send-request> – source="[hostname]" nebo source="[ip]" bylo použito mimo kontext reálného webového/soketového spojení.
• <send-request type="error" detail="Behem ziskavani OAuth ticketu doslo k chybe" id="{id}"> + vnořené diagnostické uzly error + </send-request> – odeslání požadavku selhalo a při získávání OAuth tokenu vznikly diagnostické záznamy.
• <send-request type="error" detail="{text}" id="{id}" http-state="{n}"/> – HTTP volání selhalo bez diagnostických záznamů; sebeuzavírající, detail je jeden z: syrový obsah částečně přijaté odpovědi (byla-li nějaká data přijata), "Status odpovedi se neschoduje s pozadovanym" (přijatý http-state se liší od požadovaného accepted-state), nebo "Pri provadeni doslo k nezname chybe". Text „neschoduje“ je součástí odpovědi serveru.
• Výraz pro identifikaci chyb v odpovědi serveru: send-request[@type='error'].

Související požadavky

• action – spuštění interní SOAP akce, na rozdíl od send-request bez odchozího síťového volání na cizí server.