Volání externích HTTP služeb přes API server

API server umožňuje odesílat požadavky na externí HTTP služby prostřednictvím zabezpečené proxy. Proxy lze volat přímo pomocí Web API.

Externí požadavek lze odeslat pouze na adresu povolenou správcem v souboru APIServer.yaml. Volající uživatel musí mít současně přidělené právo API funkce - Externí HTTP požadavky - Vykonat. Pokud není povolen žádný cíl, API server všechna externí volání odmítne.

Zprovoznění externích požadavků

  1. V sekci externalRequests.targets souboru APIServer.yaml povolte požadované cíle.
  2. Doporučeně nastavte cestu k auditnímu souboru v parametru auditLogPath.
  3. Restartujte API server. Konfigurace externích požadavků se načítá pouze při jeho spuštění.
  4. Uživateli přidělte právo Externí HTTP požadavky - Vykonat.
  5. Podle potřeby ověřte povolení cílové adresy pomocí endpointu external-request/check.

Chování uživatelských komponent webového rozhraní

Funkce http(...) rozlišuje adresy podle jejich cíle. Relativní adresy a absolutní adresy se stejnou základní adresou jako webové rozhraní se volají přímo. Absolutní adresy jiného serveru se automaticky předávají zabezpečené proxy API serveru.

Uživatelská komponenta může předat HTTP metodu, URL a volitelné tělo ve formátu JSON. Vlastní HTTP hlavičky, textové tělo, soubory a formuláře typu multipart současná funkce http(...) pro externí cíle nepředává.

Z odpovědi externí služby poskytuje funkce http(...) komponentě hodnoty status a body. Úplná obálka odpovědi je dostupná při přímém volání endpointu.

Přihlašovací údaje zapsané ve zdrojovém textu komponenty mohou být dostupné uživatelům, kteří smějí komponentu upravovat. Používejte pouze samostatné a odvolatelné přihlašovací údaje určené pro danou externí službu.

Kontrola povolení cílové adresy

Endpoint ověří URL proti seznamu povolených cílů. Neprovádí DNS dotaz ani neodesílá požadavek na externí službu.

GET /{spojení}/external-request/check?url=https://api.partner.cz/v2/orders

Příklad odpovědi:

{
  "allowed": true,
  "rule": "https://api.partner.cz/v2/",
  "reason": null
}

Hodnota allowed: true potvrzuje pouze shodu se seznamem povolených cílů. Překlad adresy a kontrola, zda cíl nesměřuje do zakázaného síťového rozsahu, proběhnou až při skutečném volání.

Přímé volání externího požadavku

Požadavek se odesílá metodou POST:

POST /{spojení}/external-request

Příklad těla požadavku:

{
  "method": "POST",
  "url": "https://api.partner.cz/v2/orders",
  "headers": {
    "X-Api-Key": "..."
  },
  "body": {
    "orderId": 42
  },
  "componentPath": "OrderSync"
}

Povinné jsou položky method a url. Podporované metody jsou GET, POST, PUT, PATCH a DELETE. Požadavek může obsahovat nejvýše jednu z položek body a bodyText. Položka componentPath slouží k identifikaci zdroje požadavku v auditu a monitoringu.

Příklad odpovědi:

{
  "status": 201,
  "contentType": "application/json; charset=utf-8",
  "headers": {
    "content-type": [
      "application/json; charset=utf-8"
    ],
    "location": [
      "https://api.partner.cz/v2/orders/1017"
    ]
  },
  "body": {
    "id": 1017,
    "state": "created"
  },
  "bodyText": null,
  "binaryOmitted": false
}
Položka Popis
status Stavový kód vrácený externí službou.
contentType Typ obsahu odpovědi externí služby.
headers Hlavičky konečné odpovědi. Názvy jsou uvedeny malými písmeny a každá hodnota je vrácena jako pole.
body Odpověď převedená do JSON.
bodyText Textová odpověď, pokud ji nelze vrátit v položce body.
binaryOmitted Hodnota true znamená, že externí služba vrátila binární obsah, který proxy do odpovědi nezařadila.

Úspěšné provedení proxy vrací HTTP stav 200. Skutečný stav odpovědi externí služby je uveden v položce status. Jiný HTTP stav samotné proxy znamená, že API server požadavek odmítl nebo jej nebylo možné provést.

Zabezpečení a omezení

  • Externí službě se nepředávají přihlašovací tokeny, cookies ani jiné přihlašovací údaje uživatele systému.
  • Povoleny jsou pouze protokoly HTTP a HTTPS.
  • Každý cíl přesměrování se znovu ověřuje proti seznamu povolených cílů.
  • Privátní a interní adresy jsou ve výchozím stavu zakázané. Lze je povolit nastavením allowPrivate u konkrétního pravidla.
  • Metadata adresy cloudových platforem zůstávají blokované i po povolení privátních adres.
  • Velikost odpovědi, počet přesměrování, doba zpracování a četnost požadavků jsou omezeny hodnotami v sekci externalRequests.

Audit a monitoring

Pokud je nastaven parametr auditLogPath, zapisuje API server informace o externích požadavcích do auditního souboru ve formátu JSON Lines. Hodnoty HTTP hlaviček ani těla požadavků a odpovědí se do auditního souboru nezapisují.

Souhrnný přehled volání je dostupný také prostřednictvím monitoringu externích HTTP požadavků.

Chybové kódy

Kód HTTP stav Význam
22524 403 Cílová adresa nevyhovuje žádnému povolenému pravidlu.
22525 400 Cílová adresa není platná.
22526 400 Požadavek neobsahuje platnou obálku nebo používá nepovolenou hlavičku, metodu či tělo.
22527 403 Cíl směřuje na blokovanou privátní, interní nebo metadata adresu.
22528 403 Cíl přesměrování není povolen.
22529 502 Cílová adresa přesměrování není platná.
22530 502 Byl překročen maximální počet přesměrování.
22531 502 Externí služba není dostupná nebo vypršel časový limit požadavku.
22532 502 Odpověď externí služby překročila povolenou velikost.
22533 429 Byl překročen limit souběžných požadavků nebo počet požadavků za minutu.
22534 403 Uživatel nemá potřebné právo nebo nemá povolený přístup k API.
22535 500 API server nemá k dispozici identitu volajícího.
22536 500 Kontrolu přístupového práva nebylo možné provést.