← Cloudflare Fundamentals / fundamentals / api / how-to

Volání API

Jakmile vytvořit svůj API token, jsou všechny žádosti API autorizovány stejným způsobem. Cloudflare používá Standard RFC ↗ Authorization: Bearer <API_TOKEN> rozhraní. Příklad požadavku najdete níže.

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer YQSn-xWAQiiEh9qM58wZNnyQS7FUdoqGIUAbrh7T"

Nikdy neposílejte ani neukládejte tajný klíč API tokenu v prostém textu. Zároveň dbejte na to, abyste jej nevkládali do repozitářů kódu, zejména veřejných.

Zvažte definici proměnné prostředí pro ID zóny nebo účtu a také pro přihlašovací údaje (například token API).

Chcete-li zformátovat výstup JSON pro lepší čitelnost v příkazovém řádku, můžete použít nástroj jako jq, procesor JSON pro příkazový řádek. Další informace o získání a instalaci najdete v jq, přečtěte si Stáhněte si jq ↗.

Následující příklad naformátuje výstup JSON z curl pomocí jq:

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq .

Každý prvek rozhraní Cloudflare API je vázán na číslo verze. Nejnovější verzí je verze 4. Stabilní základní adresa URL pro všechny koncové body HTTPS verze 4 je: https://api.cloudflare.com/client/v4/

Konkrétní pokyny k vytváření volání API najdete v následujících zdrojích:

• Produktu sekce Developer Docs pro návody.
• Dokumentace schématu API pro datové obsahy požadavků a odpovědí pro každý koncový bod.
• Oficiální knihovny pro Go ↗, TypeScript ↗, Python ↗, nebo Terraform od HashiCorp ↗.

Některé koncové body Cloudflare mají volitelné parametry dotazu pro filtrování výsledků, například List Zones.

Při přidávání těchto parametrů dotazu nezapomeňte uzavřít adresu URL do dvojitých uvozovek "" (stejně jako hodnoty hlaviček), jinak může volání API selhat.

curl "https://api.cloudflare.com/client/v4/zones?account.id=$ACCOUNT_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Řetězce můžete uzavřít buď do jednoduchých uvozovek ('') nebo dvojité uvozovky (""). Použití jednoduchých uvozovek však brání nahrazování proměnných v shellech jako bash. V předchozím příkladu by to znamenalo, že $ACCOUNT_ID a $CLOUDFLARE_API_TOKEN proměnné prostředí by nebyly nahrazeny svými hodnotami.

Někdy může být výsledků příliš mnoho na to, aby se zobrazily v rámci výchozí velikosti stránky, a proto se může zobrazit například následující:

"count": 1,
"page": 1,
"per_page": 20,
"total_count": 200,

K dispozici jsou dvě možnosti parametrů dotazu, které lze kombinovat pro stránkování výsledků.

• page=x umožňuje vybrat konkrétní stránku.
• per_page=xx umožňuje upravit počet výsledků zobrazených na stránce. Pokud jich zvolíte příliš mnoho, může dojít k vypršení časového limitu.

Příkladem může být https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?per_page=100&page=2.

Další možnosti jsou:

• order: Vyberte atribut, podle kterého se má řadit.
• direction: Buď ASC (vzestupné pořadí) nebo DESC (sestupné pořadí).

Dostupné možnosti budou uvedeny na konci result_info všech endpointů v Dokumentace API.

Nedávné verze Windows 10 a 11 již obsahují nástroj curl ↗ použité v příkladech API v dokumentaci pro vývojáře. Pokud používáte jinou verzi Windows, přejděte na Stahování pro Windows ↗ na webu curl, kde najdete více informací o získání a instalaci tohoto nástroje.

Chcete-li používat Cloudflare API s curl v okně Command Prompt, musíte použít dvojité uvozovky (") jako oddělovače řetězců.

Typický PATCH požadavek bude vypadat podobně jako následující:

C:\>curl --request PATCH "https://api.cloudflare.com/client/v4/user/invites/{id}" --header "X-Auth-Email: <EMAIL>" --header "X-Auth-Key: <API_KEY>" --data "{""status"": ""accepted""}"

Chcete-li escapovat znak dvojité uvozovky v těle požadavku (například u těla zadaného pomocí -d nebo --data v POST/PATCH požadavku), přidejte před něj další uvozovku (") nebo zpětné lomítko (\) znak.

Chcete-li rozdělit jeden příkaz na dva nebo více řádků, použijte ^ jako znak pokračování řádku na jeho konci:

C:\>curl --request PATCH ^
"https://api.cloudflare.com/client/v4/user/invites/{id}" ^
--header "X-Auth-Email: <EMAIL>" ^
--header "X-Auth-Key: <API_KEY>" ^
--data "{""status"": ""accepted""}"

PowerShell má specifické cmdlety (Invoke-RestMethod a ConvertFrom-Json) pro volání REST API a zpracování odpovědí JSON. Syntaxe těchto cmdletů se liší od příkladů curl uvedených v dokumentaci pro vývojáře.

Následující příklad používá Invoke-RestMethod cmdlet:

Invoke-RestMethod -URI "https://api.cloudflare.com/client/v4/zones/$Env:ZONE_ID/ssl/certificate_packs?ssl_status=all" -Method 'GET' -Headers @{'X-Auth-Email'=$Env:CLOUDFLARE_EMAIL;'X-Auth-Key'=$Env:CLOUDFLARE_API_KEY}

result      : {@{id=78411cfa-5727-4dc1-8d4a-773d01f17c7c; type=universal; hosts=System.Object[];
              primary_certificate=c173c8a1-9724-4e96-a748-2c4494186098; status=active; certificates=System.Object[];
              created_on=2022-12-09T23:11:06.010263Z; validity_days=90; validation_method=txt;
              certificate_authority=lets_encrypt}}
result_info : @{page=1; per_page=20; total_pages=1; count=1; total_count=1}
success     : True
errors      : {}
messages    : {}

Příkaz předpokládá, že proměnné prostředí ZONE_ID, CLOUDFLARE_EMAIL, a CLOUDFLARE_API_KEY byly již dříve definovány. Další informace najdete v Proměnné prostředí.

Ve výchozím nastavení bude výstup obsahovat pouze první úroveň hierarchie objektu JSON (v uvedeném příkladu obsah objektů, jako je hosts a certificates se nezobrazuje). Chcete-li zobrazit další úrovně a naformátovat výstup jako jq nástroje můžete použít ConvertFrom-Json cmdlet a zadejte požadovanou maximální hloubku (ve výchozím nastavení 2):

Invoke-RestMethod -URI "https://api.cloudflare.com/client/v4/zones/$Env:ZONE_ID/ssl/certificate_packs?ssl_status=all" -Method 'GET' -Headers @{'X-Auth-Email'=$Env:CLOUDFLARE_EMAIL;'X-Auth-Key'=$Env:CLOUDFLARE_API_KEY} | ConvertTo-Json -Depth 5

{
	"result": [
		{
			"id": "78411cfa-5727-4dc1-8d4a-773d01f17c7c",
			"type": "universal",
			"hosts": ["*.example.com", "example.com"],
			"primary_certificate": "c173c8a1-9724-4e96-a748-2c4494186098",
			"status": "active",
			"certificates": [
				{
					"id": "c173c8a1-9724-4e96-a748-2c4494186098",
					"hosts": ["*.example.com", "example.com"],
					"issuer": "LetsEncrypt",
					"signature": "ECDSAWithSHA384",
					"status": "active",
					"bundle_method": "ubiquitous",
					"zone_id": "<ZONE_ID>",
					"uploaded_on": "2023-02-02T11:20:25.403338Z",
					"modified_on": "2022-12-08T00:26:15.577555Z",
					"expires_on": "2023-03-07T23:26:12.000000Z",
					"priority": null
				}
			],
			"created_on": "2022-12-09T23:11:06.010263Z",
			"validity_days": 90,
			"validation_method": "txt",
			"certificate_authority": "lets_encrypt"
		}
	]
	// (...)
}

Nástroj curl můžete použít i v PowerShellu. V PowerShellu ale curl je alias pro Invoke-WebRequest cmdlet, který používá jinou syntaxi než obvyklý nástroj curl. Chcete-li použít curl, zadejte curl.exe místo toho.

Typický PATCH požadavek pomocí curl bude vypadat podobně jako následující:

curl.exe --request PATCH "https://api.cloudflare.com/client/v4/user/invites/{id}" --header "Authorization: Bearer $Env:CLOUDFLARE_API_TOKEN" --data '{\"status\": \"accepted\"}'

Chcete-li escapovat dvojitou uvozovku (") v těle požadavku (zadaný pomocí -d nebo --data), uveďte před ním další dvojitou uvozovku (") nebo zpětné lomítko (\). Dvojité uvozovky musíte escapovat i při použití jednoduchých uvozovek (') jako oddělovače řetězců.

Chcete-li rozdělit jeden příkaz na dva nebo více řádků, použijte zpětný apostrof (`) jako znak pro pokračování řádku na konci řádku:

curl.exe --request PATCH `
"https://api.cloudflare.com/client/v4/user/invites/{id}" `
--header "X-Auth-Email: $Env:CLOUDFLARE_EMAIL" `
--header "X-Auth-Key: $Env:CLOUDFLARE_API_KEY" `
--data '{\"status\": \"accepted\"}'

Pro hodnoty, které se opakují mezi příkazy, například ID zóny nebo účtu, si můžete definovat proměnné prostředí. Platnost proměnné prostředí může být omezena na aktuální relaci shellu, na všechny budoucí relace aktuálního uživatele, nebo dokonce na všechny budoucí relace všech uživatelů na počítači, kde ji definujete.

Přihlašovací údaje (API token, API klíč a e-mail) můžete uchovávat i pomocí proměnných prostředí a znovu je používat v různých příkazech. Tyto hodnoty ale definujte v co nejmenším rozsahu, tedy buď jen pro aktuální relaci shellu, nebo pro všechny budoucí relace aktuálního uživatele.

Postup nastavení proměnných prostředí a odkazování na ně závisí na vaší platformě a shellu.

export ZONE_ID='f2ea6707005a4da1af1b431202e96ac5'

$Env:ZONE_ID='f2ea6707005a4da1af1b431202e96ac5'

[Environment]::SetEnvironmentVariable("ZONE_ID", "f2ea6707005a4da1af1b431202e96ac5", "User")

set ZONE_ID=f2ea6707005a4da1af1b431202e96ac5

setx ZONE_ID f2ea6707005a4da1af1b431202e96ac5

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Invoke-RestMethod -URI "https://api.cloudflare.com/client/v4/zones/$Env:ZONE_ID" -Method 'GET' -Headers @{'Authorization'="Bearer $Env:CLOUDFLARE_API_TOKEN"}

curl "https://api.cloudflare.com/client/v4/zones/%ZONE_ID%" --header "Authorization: Bearer %CLOUDFLARE_API_TOKEN%"