INTEGRITY Dokumentace

← Cloudflare Workers / workers / ci-cd / builds

Referenční příručka API pro Builds

Tento průvodce ukazuje, jak používat Workers Builds REST API pro programové spouštění sestavení, správu triggerů a sledování stavu sestavení. Příklady používají curl příkazy, které lze spustit přímo v terminálu nebo upravit pro preferovaný programovací jazyk. Některé příklady přesměrovávají výstup rourou do jq ↗ k filtrování JSON odpovědí, nainstalujte si ho, pokud ho ještě nemáte.

Než začnete

1. Vytvořte API token se správnými oprávněními

Chcete-li používat Builds API, potřebujete pro ověřování požadavků API token. Builds API vyžaduje s rozsahem uživatele API token. Tokeny s rozsahem na úrovni účtu nejsou podporovány a vrátí chybu "Invalid token".

Vytvořte svůj token na dash.cloudflare.com/profile/api-tokens ↗ s následujícími oprávněními:

Oprávnění Úroveň přístupu Proč to potřebujete
Konfigurace Workers Builds Úprava Spouštějte buildy, spravujte triggery, konfigurujte proměnné prostředí
Workers Scripts Čtení Potřebné pouze pro jeden koncový bod pro načtení tagu vašeho Workeru (dokumentováno jako external_script_id)

2. Štítky Workeru (dokumentováno jako external_script_id)

Rozhraní Builds API identifikuje Workery podle jejich značka, neměnné UUID přidělené Cloudflare. V odpovědích a parametrech API se tato hodnota zobrazuje jako external_script_id.

Identifikátor Příklad Odkud pochází
Název Workeru (id) my-worker Název, který jste zadali svému Workeru
Tag Workeru (external_script_id) 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d Neměnné UUID přidělené Cloudflare

Každý koncový bod Builds API, který odkazuje na Worker, vyžaduje značka, nikoli název.

3. Co je trigger?

A trigger je konfigurace, která definuje, jak se váš Worker sestavuje a nasazuje. Určuje příkaz pro sestavení, příkaz pro nasazení, proměnné prostředí a to, které větve mají spouštět sestavení. Každý Worker má až dva triggery: jeden pro produkci (běží na vašem produkční větev) a jeden pro náhledy (spouští se ve všech ostatních větvích). Pro nastavení triggerů si přečtěte Nastavit Workers Builds od začátku.

Pole triggeru:

Pole Typ Popis
trigger_name string Zobrazovaný název triggeru
build_token_uuid string UUID tokenu sestavení použitého k nasazení Workeru. Najdete ho na stránce vašeho Workeru Nastavení > Builds > API token sekci, nebo prostřednictvím GET /builds/tokens koncový bod.
build_command string Příkaz pro sestavení projektu (například npm run build)
deploy_command string Příkaz pro nasazení Workeru (například npx wrangler deploy)
root_directory string Cesta ke kořenovému adresáři vašeho projektu
branch_includes array Vzory názvů větví, které spouštějí buildy (například ["main"] nebo ["*"])
branch_excludes array Vzory větví k vyloučení
path_includes array Vzory cest k souborům, které spouštějí sestavení
path_excludes array Vzory cest k souborům, které se mají ignorovat
build_caching_enabled boolean Povolit nebo zakázat ukládání sestavení do mezipaměti
environment_variables objekt Proměnné sestavení specifické pro tento trigger

Přehled workflow

Většina operací Builds API se řídí tímto postupem: nejprve zjistíte tag svého Workeru, poté UUID triggeru a následně provedete operace sestavení.

Přehled workflow: nejprve získejte tag Workeru, poté UUID triggeru a následně proveďte operace sestavení.
Krok Akce Endpoint
1 Získat tag Workeru GET /workers/scripts
2 Získat UUID spouštěče GET /builds/workers/:worker_tag/triggers
3a Spustit build POST /builds/triggers/:trigger_uuid/builds
3b Vypsat sestavení GET /builds/workers/:worker_tag/builds
3c Získat protokoly sestavení GET /builds/builds/:build_uuid/logs
3d Zrušení buildu PUT /builds/builds/:build_uuid/cancel

Krok 1: Získejte tag svého Workeru

Zavolejte Workers Scripts API k výpisu všech vašich Workers a vyhledání tag pro Worker, se kterým chcete pracovat:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {name: .id, tag: .tag}'

Příklad výstupu:

{
  "name": "my-worker",
  "tag": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
}
{
  "name": "another-worker",
  "tag": "8a1b2c3d4e5f67890abcdef123456789"
}

Uložte tag hodnota pro váš Worker. Použijete ji ve všech následujících voláních API.

Krok 2: Získejte UUID triggeru

Použijte GET /builds/workers/{tag}/triggers koncový bod pro výpis triggerů vašeho Workeru:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {trigger_uuid, trigger_name, branch_includes, branch_excludes}'

Příklad výstupu:

{
  "trigger_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "trigger_name": "Deploy production",
  "branch_includes": ["main"],
  "branch_excludes": []
}
{
  "trigger_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trigger_name": "Deploy non-production branches",
  "branch_includes": ["*"],
  "branch_excludes": ["main"]
}

Uložte trigger_uuid pro trigger, se kterým chcete pracovat. Nezapomeňte, že budete mít nejvýše dva triggery: jeden pro produkční větev (například main) který nasazuje do vašeho ostrého Workeru, a volitelně jeden pro všechny ostatní větve, který vytváří náhledová nasazení.

Krok 3: Práce se sestaveními

Nyní, když máte tag Workeru a UUID triggeru, můžete spouštět sestavení, zobrazovat historii sestavení a získávat logy.

Spustit manuální build

Použijte POST /builds/triggers/{uuid}/builds koncový bod s trigger_uuid z Krok 2.

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"branch": "main"}'

Musíte zadat branch, commit_hash, nebo obojí:

Pole Popis
branch Název větve Git pro sestavení (například main)
commit_hash Konkrétní commit SHA k sestavení. Pokud je zadán bez branch, sestaví commit v jeho aktuální větvi.

Odpověď obsahuje build_uuid který můžete použít ke sledování buildu.

Vypsat sestavení pro Worker

Použijte GET /builds/workers/{tag}/builds koncový bod s worker_tag z Krok 1.

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {build_uuid, status, branch, created_at}'

Odpověď obsahuje build_uuid pro každé sestavení, které budete potřebovat pro získání protokolů nebo zrušení sestavení.

Získat protokoly sestavení

Použijte GET /builds/builds/{uuid}/logs koncový bod. Získejte build_uuid z:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/logs" \
  --header "Authorization: Bearer <API_TOKEN>"

Zrušení běžícího buildu

Použijte PUT /builds/builds/{uuid}/cancel koncový bod. Získejte build_uuid z:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/cancel" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request PUT

Aktualizovat konfiguraci triggeru

Použijte PATCH /builds/triggers/{uuid} koncový bod s trigger_uuid z Krok 2. Můžete aktualizovat kterékoli z polí triggeru popsaných v Co je trigger?.

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "build_command": "npm run build:prod",
    "deploy_command": "npx wrangler deploy"
  }'

Správa proměnných prostředí sestavení

Proměnné prostředí se nastavují pro každý trigger zvlášť, takže můžete mít odlišné hodnoty pro produkční a preview sestavení. Můžete například nastavit NODE_ENV=production na vašem produkčním triggeru a NODE_ENV=development na vašem preview triggeru. Více informací najdete v referenční dokumentace k API proměnných prostředí pro úplné podrobnosti o endpointu.

Vypsat proměnné prostředí

Použijte trigger_uuid z Krok 2.

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>"

Nastavit proměnné prostředí

Pro každý trigger můžete nastavit odlišné proměnné. Chcete-li například nastavit proměnné produkčního prostředí:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "production", "is_secret": false},
    "API_KEY": {"value": "prod-secret-key", "is_secret": true}
  }'

A jiné hodnoty pro preview sestavení:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{preview_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "development", "is_secret": false},
    "API_KEY": {"value": "dev-secret-key", "is_secret": true}
  }'

Nastavte is_secret na false pro obyčejné hodnoty a true pro citlivé hodnoty, které by měly být v protokolech maskovány.

Odstranit proměnnou prostředí

Použijte trigger_uuid z Krok 2. variable_key je název klíče, který jste nastavili (například NODE_ENV).

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables/{variable_key}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request DELETE

Vymazání mezipaměti sestavení

Použijte POST /builds/triggers/{uuid}/purge_build_cache koncový bod s trigger_uuid z Krok 2. Tím se pro daný trigger vymažou cachované závislosti a build artefakty.

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/purge_build_cache" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request POST

Příklady

Následující příklady ukazují běžné případy použití Builds API.

Nastavit Workers Builds od začátku

Tento příklad provází celým procesem propojení repozitáře GitHub s Workerem a nastavením automatizovaných sestavení pouze pomocí API.

Postup nastavení: získejte GitHub ID, vytvořte propojení repozitáře, získejte tag Workeru, vytvořte triggery, nastavte proměnné prostředí a spusťte první sestavení.
Krok Akce Endpoint
1 Získání ID účtu/repozitáře GitHub GET api.github.com/users/... a GET api.github.com/repos/...
2 Vytvoření připojení k repozitáři PUT /builds/repos/connections
3 Získat tag Workeru GET /workers/scripts
4 Získat UUID tokenu sestavení GET /builds/tokens
5a Vytvoření produkčního triggeru POST /builds/triggers
5b Vytvoření preview triggeru POST /builds/triggers
6 Nastavit proměnné prostředí PATCH /builds/triggers/:trigger_uuid/environment_variables
7 Spustit první build POST /builds/triggers/:trigger_uuid/builds

Předpoklady

Než začnete API používat, musíte nejprve přes dashboard nainstalovat aplikaci Cloudflare GitHub App:

  1. Přejděte na Workers & Pages v Cloudflare dashboard ↗.
  2. Vyberte libovolný Worker a přejděte do Nastavení > Builds > Připojit.
  3. Vyberte GitHub a autorizujte Cloudflare GitHub App pro váš účet nebo organizaci.

Toto jednorázové nastavení vytvoří propojení mezi vaším účtem GitHub a Cloudflare. Po dokončení už pro vše ostatní můžete používat API.

Krok 1: Získejte informace o svém účtu GitHub

Po instalaci GitHub App budete potřebovat ID svého účtu GitHub a ID repozitáře. Najdete je u existujícího triggeru nebo v GitHub API.

Z GitHub API:

# Get your GitHub user/org ID
curl -s "https://api.github.com/users/<GITHUB_USERNAME>" | jq '.id'

# Get a repository ID
curl -s "https://api.github.com/repos/<GITHUB_USERNAME>/<REPO_NAME>" | jq '.id'

Krok 2: Vytvořte propojení repozitáře

Vytvořte propojení mezi svým repozitářem GitHub a Cloudflare:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/repos/connections" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "provider_type": "github",
    "provider_account_id": "<GITHUB_USER_ID>",
    "provider_account_name": "<GITHUB_USERNAME>",
    "repo_id": "<GITHUB_REPO_ID>",
    "repo_name": "<REPO_NAME>"
  }'

Uložte repo_connection_uuid z odpovědi.

Krok 3: Získejte tag svého Workeru

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {name: .id, tag: .tag}'

Krok 4: Získejte UUID tokenu sestavení

Build token autorizuje systém sestavení k nasazení vašeho Workeru. UUID svého build tokenu získáte takto:

  1. Přejděte ke svému Workeru v Cloudflare dashboard ↗.
  2. Přejděte na Nastavení > Builds > API token.
  3. Vyberte existující build token nebo vytvořte nový.

Své build tokeny můžete také vypsat pomocí API:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/tokens" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {build_token_uuid, build_token_name}'

Uložte build_token_uuid pro další krok.

Krok 5: Vytvořte produkční trigger

Vytvořte trigger, který nasadí aplikaci při push do main:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "external_script_id": "<WORKER_TAG>",
    "repo_connection_uuid": "<REPO_CONNECTION_UUID>",
    "build_token_uuid": "<BUILD_TOKEN_UUID>",
    "trigger_name": "Deploy production",
    "build_command": "npm run build",
    "deploy_command": "npx wrangler deploy",
    "root_directory": "/",
    "branch_includes": ["main"],
    "branch_excludes": [],
    "path_includes": ["*"],
    "path_excludes": []
  }'

Krok 6: Vytvořte náhledový trigger (volitelné)

Vytvořte druhý trigger pro preview nasazení na všech ostatních větvích:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "external_script_id": "<WORKER_TAG>",
    "repo_connection_uuid": "<REPO_CONNECTION_UUID>",
    "build_token_uuid": "<BUILD_TOKEN_UUID>",
    "trigger_name": "Deploy preview branches",
    "build_command": "npm run build",
    "deploy_command": "npx wrangler versions upload",
    "root_directory": "/",
    "branch_includes": ["*"],
    "branch_excludes": ["main"],
    "path_includes": ["*"],
    "path_excludes": []
  }'

Všimněte si odlišných deploy_command: produkce používá wrangler deploy zatímco preview používá wrangler versions upload pro vytváření náhledových URL adres bez vlivu na živé nasazení.

Krok 7: Nastavte proměnné prostředí pro každý trigger

Nastavte proměnné prostředí pro produkci:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "production", "is_secret": false}
  }'

Nastavte proměnné prostředí pro preview:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{preview_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "development", "is_secret": false}
  }'

Krok 8: Spusťte první sestavení

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"branch": "main"}'

Váš Worker je nyní propojen s GitHubem. Budoucí pushe do main automaticky spustí produkční nasazení a pushe do ostatních větví vytvoří náhledová nasazení.

Znovu nasadit aktuální nasazení

Znovu nasaďte své aktuální aktivní nasazení, abyste obnovili data z doby sestavení. To je užitečné, když potřebujete provést nové sestavení bez změn kódu.

Postup opětovného nasazení: získejte aktivní nasazení, najděte build pro danou verzi a znovu jej spusťte se stejnou branch a commitem.
Krok Akce Endpoint
1 Získat aktivní nasazení GET /workers/scripts/:worker_name/deployments
2 Najděte sestavení pro danou verzi GET /builds/builds?version_ids=:version_id
3 Znovu spustit se stejnou větví/commitem POST /builds/triggers/:trigger_uuid/builds

Krok 1: Získejte ID verze aktivního nasazení

Použijte GET /workers/scripts/{script_name}/deployments koncový bod s worker_name z Krok 1:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{worker_name}/deployments" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result.deployments[0].versions[0].version_id'

Uložte version_id z výstupu.

Krok 2: Najděte sestavení pro danou verzi

Použijte GET /builds/builds koncový bod s version_id z předchozího kroku:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds?version_ids={version_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result.builds'

Z odpovědi si poznamenejte trigger.trigger_uuid, build_trigger_metadata.branch, a build_trigger_metadata.commit_hash.

Krok 3: Znovu spusťte se stejnou branch a commitem

Použijte POST /builds/triggers/{uuid}/builds koncový bod s hodnotami z předchozího kroku:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "branch": "{branch}",
    "commit_hash": "{commit_hash}"
  }'

Passing both `branch` and `commit_hash` pins the build to that exact commit on that branch.

Řešení potíží

"Resource not found" error

Pravděpodobně používáte název Workeru místo tagu Workeru. Builds API vyžaduje tag (UUID, například 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d), nikoli název Workeru. Viz Krok 1 k získání tagu vašeho Workeru.

Ostatní chyby sestavení najdete v Řešení problémů s buildy.