← Cloudflare Fundamentals / fundamentals / api / how-to

Выполняйте вызовы API

После того как вы создание API-токена, все запросы API авторизуются одинаково. Cloudflare использует Стандарт RFC ↗ Authorization: Bearer <API_TOKEN> интерфейс. Пример запроса показан ниже.

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

Никогда не передавайте и не храните секрет API-токена в открытом виде. Также не добавляйте его в репозитории кода, особенно в публичные.

Рекомендуется определить переменные окружения для идентификатора зоны или учетной записи, а также для учетных данных аутентификации (например, API-токена).

Чтобы сделать вывод JSON более читаемым в командной строке, можно использовать инструмент вроде jq, консольный JSON-процессор. Подробнее о том, как его получить и установить, читайте jq, см. Загрузите jq ↗.

В следующем примере вывод curl в формате JSON форматируется с помощью jq:

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

Использование API Cloudflare

Каждый элемент API Cloudflare привязан к номеру версии. Актуальная версия: Version 4. Стабильный базовый URL-адрес для всех конечных точек HTTPS Version 4: https://api.cloudflare.com/client/v4/

Конкретные инструкции по выполнению вызовов API см. в следующих материалах:

Продукта раздел документации для разработчиков для пошаговых руководств.
Документация по схеме API для тела запроса и ответа для каждой конечной точки.
Официальные библиотеки для Go ↗, TypeScript ↗, Python ↗, или Terraform от HashiCorp ↗.

Параметры запроса

Некоторые конечные точки Cloudflare поддерживают необязательные параметры запроса для фильтрации результатов, например List Zones.

При добавлении этих параметров запроса обязательно заключайте URL в двойные кавычки "" (как и значения заголовков), иначе вызов API может завершиться ошибкой.

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

Вы можете заключать строки в одинарные кавычки ('') или двойные кавычки (""). Однако использование одинарных кавычек не позволяет выполнять подстановку переменных в таких оболочках, как bash. В предыдущем примере это означало бы, что $ACCOUNT_ID и $CLOUDFLARE_API_TOKEN переменные окружения не будут заменены своими значениями.

Пагинация

Иногда количество результатов превышает размер страницы по умолчанию, и тогда вы можете получить, например, следующее:

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

Существует два варианта параметров запроса, которые можно комбинировать для постраничного вывода результатов.

page=x позволяет выбрать конкретную страницу.
per_page=xx позволяет изменить количество результатов, отображаемых на странице. Если выбрать слишком большое значение, может произойти тайм-аут.

Примером может служить https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?per_page=100&page=2.

Другие варианты:

order: Выберите атрибут для сортировки.
direction: Либо ASC (по возрастанию) или DESC (по убыванию).

Доступные варианты будут перечислены в конце result_info всех конечных точек в Документация по API.

Вызовы API в Windows

Последние версии Windows 10 и 11 уже включают инструмент curl ↗ используемая в примерах API документации для разработчиков. Если вы используете другую версию Windows, см. Загрузки для Windows ↗ на сайте curl, чтобы узнать больше о получении и установке этого инструмента.

Использование окна Command Prompt

Чтобы использовать Cloudflare API вместе с curl в окне Command Prompt, необходимо использовать двойные кавычки (") в качестве разделителей строк.

Типичный PATCH запрос будет выглядеть примерно так:

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

Чтобы экранировать символ двойной кавычки в теле запроса (например, если тело запроса указано с -d или --data в POST/PATCH запрос), добавьте перед ней ещё одну двойную кавычку (") или обратную косую черту (\) символ.

Чтобы разбить одну команду на две и более строк, используйте ^ как символ переноса строки в конце строки:

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

В PowerShell есть специальные командлеты (Invoke-RestMethod и ConvertFrom-Json) для выполнения вызовов REST API и обработки ответов в формате JSON. Синтаксис этих командлетов отличается от примеров curl, приведённых в документации для разработчиков.

В следующем примере используется 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    : {}

Команда предполагает, что переменные окружения ZONE_ID, CLOUDFLARE_EMAIL, а также CLOUDFLARE_API_KEY были определены ранее. Дополнительную информацию см. в Переменные окружения.

По умолчанию вывод содержит только первый уровень иерархии объекта JSON (в примере выше это содержимое таких объектов, как hosts и certificates не отображается). Чтобы показать дополнительные уровни и отформатировать вывод так же, как jq инструмент, вы можете использовать ConvertFrom-Json cmdlet, указав нужную максимальную глубину (по умолчанию 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"
		}
	]
	// (...)
}

Вы также можете использовать curl в PowerShell. Однако в PowerShell curl это псевдоним для Invoke-WebRequest cmdlet, который поддерживает синтаксис, отличный от обычного curl. Чтобы использовать curl, введите curl.exe взамен.

Типичный PATCH запрос с помощью curl будет выглядеть примерно так:

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

Чтобы экранировать двойную кавычку (") в теле запроса (задаётся с помощью -d или --data), добавьте перед ней ещё одну двойную кавычку (") или обратную косую черту (\). Двойные кавычки необходимо экранировать, даже если используются одинарные кавычки (') в качестве разделителей строк.

Чтобы разбить одну команду на две и более строк, используйте обратный апостроф (`) в качестве символа продолжения строки в конце строки:

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

Переменные окружения

Вы можете определять переменные среды для значений, которые повторяются в разных командах, например ID зоны или учётной записи. Время жизни переменной среды может ограничиваться текущей сессией shell, распространяться на все будущие сессии текущего пользователя или даже на все будущие сессии всех пользователей на компьютере, где вы её определяете.

Переменные среды также можно использовать для хранения учётных данных для аутентификации (API-токена, API-ключа и email) и их повторного использования в разных командах. Однако определяйте эти значения в минимально возможной области действия: либо только в текущей сессии shell, либо во всех новых сессиях текущего пользователя.

Порядок задания и использования переменных окружения зависит от платформы и оболочки.

Определите переменную окружения

Чтобы определить ZONE_ID переменную окружения для текущего сеанса оболочки, выполните следующую команду:

export ZONE_ID='f2ea6707005a4da1af1b431202e96ac5'

Чтобы определить переменную для всех новых сеансов оболочки текущего пользователя, добавьте указанную выше команду в конец файла конфигурации оболочки (например, ~/.bashrc для bash оболочку и ~/.zshrc для zsh оболочку).

Чтобы определить ZONE_ID переменную окружения для текущего сеанса PowerShell, выполните следующую команду:

$Env:ZONE_ID='f2ea6707005a4da1af1b431202e96ac5'

Чтобы определить переменную окружения для всех новых сеансов PowerShell текущего пользователя, задайте её в профиле PowerShell. Путь к профилю PowerShell можно получить, выполнив echo $PROFILE.

Либо задайте переменную для всех новых сеансов PowerShell текущего пользователя с помощью SetEnvironmentVariable() метод объекта System.Environment класс. Например:

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

Выполнение этой команды не повлияет на текущий сеанс. Вам нужно будет закрыть его и открыть новый сеанс PowerShell.

Чтобы определить ZONE_ID переменную окружения для текущего сеанса Command Prompt, выполните следующую команду:

set ZONE_ID=f2ea6707005a4da1af1b431202e96ac5

Чтобы определить переменную окружения для всех будущих сеансов Command Prompt текущего пользователя, выполните следующую команду:

setx ZONE_ID f2ea6707005a4da1af1b431202e96ac5

Выполнение этой команды не повлияет на текущее окно. Вам нужно будет либо выполнить set команду, либо закрыть окно командной строки и открыть новое.

Ссылка на переменную окружения

При обращении к переменной окружения в команде добавьте $ префикс к имени переменной (например, $ZONE_ID). Убедитесь, что вся строка, ссылающаяся на переменную, либо не заключена в кавычки (если она не содержит пробелов), либо заключена в двойные кавычки ("").

Например:

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

При обращении к переменной окружения в команде добавьте $Env: префикс к имени переменной (например, $Env:ZONE_ID). Убедитесь, что вся строка, ссылающаяся на переменную, либо не заключена в кавычки, либо заключена в двойные кавычки ("").

Например:

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

При обращении к переменной окружения в команде заключите имя переменной в % символов (например, %ZONE_ID%).

Например:

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