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トークンの秘密をプレーンテキストで送信または保存しないでください。また、特に公開のコードリポジトリにチェックインしないようにしてください。

コマンドラインでの可読性のためにJSON出力をフォーマットするには、jqのようなコマンドラインJSONプロセッサを使用できます。jqの取得とインストールに関する詳細は、Download jq ↗を参照してください。

以下の例は、jqを使用してcurlのJSON出力をフォーマットします。

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}" \
--header "Authorization: Bearer <API_TOKEN>" | jq .

CloudflareのAPIを使用する

すべてのCloudflare API要素は、バージョン番号に固定されています。最新バージョンはバージョン4です。すべてのバージョン4 HTTPSエンドポイントの安定したベースURLは次のとおりです: https://api.cloudflare.com/client/v4/

API呼び出しを行うための具体的なガイダンスについては、以下のリソースを参照してください。

製品の開発者ドキュメントセクションでのハウツーガイド。
各エンドポイントのリクエストおよびレスポンスペイロードに関するAPIスキーマドキュメント。
Go ↗、Typescript ↗、Python ↗、またはHashicorpのTerraform ↗のファーストパーティライブラリ。

クエリパラメータ

いくつかのCloudflareエンドポイントには、ゾーンのリストのように、受信結果をフィルタリングするためのオプションのクエリパラメータがあります。

これらのクエリパラメータを追加する際は、URLを引用符'で囲むことを確認してください（ヘッダー値と同様に）、さもなければAPI呼び出しがエラーになる可能性があります。

 curl 'https://api.cloudflare.com/client/v4/zones?account.id=<ACCOUNT_ID>' \
 --header 'Authorization: Bearer <CF_API_TOKEN>' \
 --header 'Content-Type: application/json'

ページネーション

時には、デフォルトのページサイズで表示するには結果が多すぎる場合があります。たとえば、次のような結果を受け取ることがあります。

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

結果をページネートするために組み合わせて使用できる2つのクエリパラメータオプションがあります。

page=xは特定のページを選択できます。
per_page=xxはページに表示される結果の数を調整できます。あまりにも多くを選択すると、タイムアウトが発生する可能性があります。

例としては、https://api.cloudflare.com/client/v4/zones/zone-identifier/dns_records?per_page=100&page=2のようになります。

他のオプションは次のとおりです：

order: 並べ替える属性を選択します。
direction: ASC（昇順）またはDESC（降順）のいずれかです。

利用可能なオプションは、APIドキュメントのすべてのエンドポイントのresult_infoの最後にリストされます。

WindowsでのAPI呼び出し

最近のWindows 10および11のバージョンには、開発者ドキュメントのAPI例で使用されるcurlツールがすでに含まれています ↗。異なるWindowsバージョンを使用している場合は、curlウェブサイトのWindowsダウンロード ↗を参照して、このツールの取得とインストールに関する詳細を確認してください。

コマンドプロンプトウィンドウを使用する

コマンドプロンプトウィンドウでcurlを使用してCloudflare APIを使用するには、シングルクォート（'）の代わりにダブルクォート（"）を文字列デリミタとして使用する必要があります。

典型的な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で指定されたボディ内）、別のダブルクォート（"）またはバックスラッシュ（\）文字を前に付けます。

1つのコマンドを2行以上に分けるには、行の最後に行継続文字として^を使用します。

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には、REST API呼び出しを行い、JSONレスポンスを処理するための特定のcmdlet（Invoke-RestMethodおよびConvertFrom-Json）があります。これらのcmdletの構文は、開発者ドキュメントで提供されているcurlの例とは異なります。

以下の例は、Invoke-RestMethod cmdletを使用しています。

PS C:\> Invoke-RestMethod -URI 'https://api.cloudflare.com/client/v4/zones/{zone_id}/ssl/certificate_packs?ssl_status=all' -Method 'GET' -ContentType 'application/json' -Headers @{'X-Auth-Email'='<EMAIL>';'X-Auth-Key'='<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    : {}

デフォルトでは、出力はJSONオブジェクト階層の最初のレベルのみを含みます（上記の例では、hostsやcertificatesのようなオブジェクトの内容は表示されません）。追加のレベルを表示し、出力をjqツールのようにフォーマットするには、ConvertFrom-Json cmdletを使用して希望する最大深度を指定します（デフォルトは2です）。

PS C:\> Invoke-RestMethod -URI 'https://api.cloudflare.com/client/v4/zones/{zone_id}/ssl/certificate_packs?ssl_status=all' -Method 'GET' -ContentType 'application/json' -Headers @{'X-Auth-Email'='<EMAIL>';'X-Auth-Key'='<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"
    }
  ]
  // (...)
}

PowerShellでもcurlツールを使用できます。ただし、PowerShellではcurlはInvoke-WebRequest cmdletのエイリアスであり、通常のcurlツールとは異なる構文をサポートしています。curlを使用するには、curl.exeと入力します。

curlを使用した典型的なPATCHリクエストは次のようになります。

PS C:\> curl.exe --request PATCH "https://api.cloudflare.com/client/v4/user/invites/{id}" --header "Authorization: Bearer <API_TOKEN>" --data '{\"status\": \"accepted\"}'

リクエストボディ内のダブルクォート（"）文字をエスケープするには（-dまたは--dataで指定）、別のダブルクォート（"）またはバックスラッシュ（\）を前に付けます。シングルクォート（'）を文字列デリミタとして使用している場合でも、ダブルクォートをエスケープする必要があります。

1つのコマンドを2行以上に分けるには、行の最後にバックティック（`）を行継続文字として使用します。

PS C:\> curl.exe --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\"}'

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings