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ů
- V sekci externalRequests.targets souboru APIServer.yaml povolte požadované cíle.
- Doporučeně nastavte cestu k auditnímu souboru v parametru auditLogPath.
- Restartujte API server. Konfigurace externích požadavků se načítá pouze při jeho spuštění.
- Uživateli přidělte právo Externí HTTP požadavky - Vykonat.
- 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. |