INTEGRITY Документация

← Cloudflare Workers / workers / ci-cd / builds

Справочник по API Builds

В этом руководстве показано, как использовать REST API Workers Builds для программного запуска сборок, управления триггерами и отслеживания статуса сборки. В примерах используется curl команды, которые можно выполнять прямо в терминале или адаптировать под предпочитаемый язык программирования. В некоторых примерах вывод передаётся через jq ↗ для фильтрации ответов JSON, установите её, если она ещё не установлена.

Прежде чем начать

1. Создайте API-токен с необходимыми правами доступа

Чтобы использовать Builds API, вам нужен API-токен для аутентификации запросов. Для Builds API требуется с областью действия на уровне пользователя API-токен. Токены с областью действия на уровне аккаунта не поддерживаются и вызывают ошибку "Invalid token".

Создайте токен по адресу dash.cloudflare.com/profile/api-tokens ↗ со следующими разрешениями:

Разрешение Уровень доступа Зачем это нужно
Конфигурация Workers Builds Изменить Запуск сборок, управление триггерами, настройка переменных окружения
Workers Scripts Чтение Требуется только для один эндпоинт чтобы получить тег вашего Worker (описан как external_script_id)

2. Теги Worker (задокументированы как external_script_id)

Builds API определяет Workers по их тег, неизменяемый UUID, присвоенный Cloudflare. В ответах API и параметрах это значение отображается как external_script_id.

Идентификатор Пример Откуда он берётся
Имя Worker (id) my-worker Имя, которое вы указали для своего Worker
Тег Worker (external_script_id) 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d Неизменяемый UUID, присвоенный Cloudflare

Для каждой конечной точки Builds API, которая ссылается на Worker, требуется тег, а не имя.

3. Что такое триггер?

A триггер представляет собой конфигурацию, которая определяет, как ваш Worker собирается и развёртывается. Она задаёт команду сборки, команду развёртывания, переменные окружения и ветки, при изменении которых запускается сборка. У каждого Worker может быть до два триггера: один для продакшена (выполняется на вашем продакшен-ветка) и один для предпросмотра (выполняется во всех остальных ветках). Инструкции по настройке триггеров см. в Настройка Workers Builds с нуля.

Поля триггера:

Поле Тип Описание
trigger_name string Отображаемое имя триггера
build_token_uuid string UUID токена сборки, используемого для развёртывания вашего Worker. Найдите его в вашем Worker Настройки > Builds > API-токен раздел, либо через GET /builds/tokens конечная точка.
build_command string Команда для сборки проекта (например, npm run build)
deploy_command string Команда для развертывания Worker (например, npx wrangler deploy)
root_directory string Путь к корню вашего проекта
branch_includes array Шаблоны веток, при совпадении с которыми запускаются сборки (например, ["main"] или ["*"])
branch_excludes array Шаблоны веток для исключения
path_includes array Шаблоны путей к файлам, запускающие сборки
path_excludes array Шаблоны путей к файлам, которые нужно игнорировать
build_caching_enabled boolean Включить или отключить кеширование сборки
environment_variables объект Переменные сборки, специфичные для этого триггера

Обзор Workflow

Большинство операций Builds API следуют одному шаблону: сначала получите tag вашего Worker, затем получите UUID триггера, а затем выполните операции сборки.

Обзор Workflow: получить тег Worker, затем получить UUID триггера, затем выполнить операции сборки.
Шаг Действие Конечная точка
1 Получение тега Worker GET /workers/scripts
2 Получить UUID триггера GET /builds/workers/:worker_tag/triggers
3a Запустить сборку POST /builds/triggers/:trigger_uuid/builds
3b Получить список сборок GET /builds/workers/:worker_tag/builds
3c Получение логов сборки GET /builds/builds/:build_uuid/logs
3d Отмена сборки PUT /builds/builds/:build_uuid/cancel

Шаг 1: Получите тег Worker

Вызовите Workers Scripts API чтобы получить список всех своих Workers и найти tag для Worker, с которым вы хотите работать:

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

Пример вывода:

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

Сохраните tag значение для вашего Worker. Вы будете использовать его во всех последующих вызовах API.

Шаг 2: Получите UUID триггера

Используйте GET /builds/workers/{tag}/triggers эндпоинт для получения списка триггеров вашего Worker:

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}'

Пример вывода:

{
  "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"]
}

Сохраните trigger_uuid для триггера, с которым вы хотите работать. Помните, что у вас будет не более двух триггеров: один для продакшен-ветки (например, main) который выполняет деплой в ваш рабочий Worker, и, при необходимости, ещё один для всех остальных веток, который создаёт деплои предпросмотра.

Шаг 3: Работа со сборками

Теперь, когда у вас есть тег Worker и UUID триггера, вы можете запускать сборки, просматривать историю сборок и получать журналы.

Запустить сборку вручную

Используйте POST /builds/triggers/{uuid}/builds эндпоинт с trigger_uuid от Шаг 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"}'

Необходимо указать branch, commit_hash, либо оба варианта:

Поле Описание
branch Имя ветки Git для сборки (например, main)
commit_hash Конкретный commit SHA для сборки. Если указан без branch, собирает коммит в его текущей ветке.

Ответ включает build_uuid который можно использовать для отслеживания сборки.

Получить список сборок для Worker

Используйте GET /builds/workers/{tag}/builds эндпоинт с worker_tag от Шаг 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}'

Ответ включает build_uuid для каждой сборки, который понадобится вам, чтобы получать логи или отменять сборки.

Получение логов сборки

Используйте GET /builds/builds/{uuid}/logs эндпоинт. Получите build_uuid из:

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

Отмена выполняющейся сборки

Используйте PUT /builds/builds/{uuid}/cancel эндпоинт. Получите build_uuid из:

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

Обновите конфигурацию триггера

Используйте PATCH /builds/triggers/{uuid} эндпоинт с trigger_uuid от Шаг 2. Вы можете изменить любое из полей триггера, описанных в Что такое триггер?.

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"
  }'

Управление переменными окружения сборки

Переменные окружения задаются отдельно для каждого триггера, поэтому вы можете использовать разные значения для продакшн и preview сборок. Например, вы можете задать NODE_ENV=production для вашего production триггера и NODE_ENV=development для вашего preview триггера. Обратитесь к справочник API переменных окружения с полным описанием эндпоинта.

Список переменных окружения

Используйте trigger_uuid от Шаг 2.

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

Настройка переменных окружения

Для каждого триггера можно задать разные переменные. Например, чтобы задать переменные окружения для продакшена:

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}
  }'

И другие значения для 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},
    "API_KEY": {"value": "dev-secret-key", "is_secret": true}
  }'

Задайте is_secret к false для простых значений и true для конфиденциальных значений, которые должны быть скрыты в логах.

Удалить переменную окружения

Используйте trigger_uuid от Шаг 2. variable_key это имя ключа, которое вы задали (например, 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

Очистка кеша сборки

Используйте POST /builds/triggers/{uuid}/purge_build_cache эндпоинт с trigger_uuid от Шаг 2. Это очищает закэшированные зависимости и артефакты сборки для данного триггера.

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

Примеры

Следующие примеры показывают типичные варианты использования Builds API.

Настройка Workers Builds с нуля

В этом примере пошагово показан весь процесс подключения репозитория GitHub к Worker и настройки автоматических сборок только через API.

План настройки: получить GitHub ID, создать подключение репозитория, получить тег Worker, создать триггеры, задать переменные окружения, запустить первую сборку.
Шаг Действие Конечная точка
1 Получение идентификаторов аккаунта/репозитория GitHub GET api.github.com/users/... и GET api.github.com/repos/...
2 Создать подключение репозитория PUT /builds/repos/connections
3 Получение тега Worker GET /workers/scripts
4 Получить UUID токена сборки GET /builds/tokens
5a Создать триггер Production POST /builds/triggers
5b Создать триггер Preview POST /builds/triggers
6 Настройка переменных окружения PATCH /builds/triggers/:trigger_uuid/environment_variables
7 Запустить первую сборку POST /builds/triggers/:trigger_uuid/builds

Предварительные требования

Прежде чем использовать API, необходимо установить приложение Cloudflare GitHub App через панель управления:

  1. Перейдите в Workers & Pages в Панель управления Cloudflare ↗.
  2. Выберите любой Worker и перейдите в Настройки > Builds > Подключить.
  3. Выберите GitHub и авторизуйте приложение Cloudflare GitHub App для своего аккаунта или организации.

Эта разовая настройка создает связь между вашим аккаунтом GitHub и Cloudflare. После её завершения всё остальное можно делать через API.

Шаг 1: Получите информацию об учетной записи GitHub

После установки GitHub App вам потребуются идентификатор аккаунта GitHub и идентификатор репозитория. Их можно найти в существующем триггере или через API GitHub.

Из API GitHub:

# 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'

Шаг 2: Создайте подключение к репозиторию

Создайте подключение между репозиторием GitHub и 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>"
  }'

Сохраните repo_connection_uuid из ответа.

Шаг 3: Получите тег Worker

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

Шаг 4: Получите UUID токена сборки

Токен сборки авторизует систему сборки для развертывания вашего Worker. Чтобы получить UUID токена сборки:

  1. Откройте своего Worker в Панель управления Cloudflare ↗.
  2. Перейдите в Настройки > Builds > API-токен.
  3. Выберите существующий токен сборки или создайте новый.

Также список токенов сборки можно получить через 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}'

Сохраните build_token_uuid для следующего шага.

Шаг 5: Создайте триггер для продакшена

Создайте триггер, разворачивающий приложение при push в 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": []
  }'

Шаг 6: Создайте триггер предпросмотра (необязательно)

Создайте второй триггер для preview-развёртываний на всех остальных ветках:

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": []
  }'

Обратите внимание на разницу в deploy_command: продакшен использует wrangler deploy тогда как предпросмотр использует wrangler versions upload чтобы создавать preview-адреса, не затрагивая продакшен-развёртывание.

Шаг 7: Задайте переменные окружения для каждого триггера

Настройте переменные окружения продакшена:

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}
  }'

Настройте переменные окружения предпросмотра:

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}
  }'

Шаг 8: Запустите первую сборку

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"}'

Теперь ваш Worker подключён к GitHub. Все последующие push в main автоматически запускает развёртывания в продакшене, а отправка изменений в другие ветки создаёт предварительные развёртывания.

Повторно развернуть текущее развёртывание

Повторно разверните текущее активное развёртывание, чтобы обновить данные времени сборки. Это полезно, если нужно выполнить пересборку без изменений в коде.

Процесс повторного развёртывания: получить активное развёртывание, найти сборку для этой версии, запустить её заново с той же веткой и коммитом.
Шаг Действие Конечная точка
1 Получение активного развёртывания GET /workers/scripts/:worker_name/deployments
2 Найдите сборку для этой версии GET /builds/builds?version_ids=:version_id
3 Повторить запуск с той же веткой/коммитом POST /builds/triggers/:trigger_uuid/builds

Шаг 1: Получите ID версии активного развертывания

Используйте GET /workers/scripts/{script_name}/deployments эндпоинт с worker_name от Шаг 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'

Сохраните version_id из вывода.

Шаг 2: Найдите сборку для этой версии

Используйте GET /builds/builds эндпоинт с version_id из предыдущего шага:

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'

В ответе обратите внимание на trigger.trigger_uuid, build_trigger_metadata.branch, а также build_trigger_metadata.commit_hash.

Шаг 3: Повторно запустите с той же веткой и коммитом

Используйте POST /builds/triggers/{uuid}/builds эндпоинт со значениями из предыдущего шага:

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.

Устранение неполадок

Ошибка «Resource not found»

Вероятно, вы используете имя Worker вместо тега Worker. Для Builds API требуется tag (UUID, например 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d), а не имя Worker. См. Шаг 1 чтобы получить тег своего Worker.

Об остальных ошибках сборки см. в Устранение неполадок со сборками.