1. Home
  2. Cloud
  3. Confluent Cloud クラスター

重要

このページの日本語コンテンツは古くなっている可能性があります。最新の英語版コンテンツをご覧になるには、こちらをクリックしてください。

Confluent Cloud クラスター管理 API クイックスタート

Confluent Cloud Console と Confluent CLI を使用して Apache Kafka® クラスターを管理できる一方、一連の REST API を使用して Kafka クラスターでさまざまな操作を実行できます。

これらの API により、クラスターの操作を自動化および効率化できます。他の Confluent Cloud API と同様に、この API は、予測可能なリソース指向の URL があり、JSON を使用してデータを転送し、標準の HTTP 動詞、応答コード、認証、および設計の原則を使用しています。

この API を使用して、ベーシッククラスター、スタンダードクラスター、専用クラスターで以下の操作を実行できます。

このトピックでは、各 API の基本的な使用方法を説明し、ベーシッククラスター、スタンダードクラスター、専用クラスターのリクエストと応答の例を示します。これらの API には、「Confluent Cloud のサービスクォータ」に記載されている制限が適用されることに注意してください。

呼び出しのパラメーターの詳細および複数の言語での例については、Cluster API リファレンス を参照してください。

ベース URL

すべてのクラスター管理呼び出しのベース URL を以下に示します。

https://api.confluent.cloud/

オブジェクトモデル

すべての Confluent オブジェクトは、以下の一連の共通プロパティを共有します。

  • api_version: オブジェクトの API バージョンを示します。これらの API のバージョンは cmk/v2 です。
  • kind: オブジェクトの種類を示します。
  • id: オブジェクトの識別子を示します。

認証

クラスターエンドポイントへの各リクエストには、Confluent Cloud API キーを含む Authorization: Basic {key} ヘッダーを含める必要があります。Confluent Cloud API キーの作成またはアクセスの詳細については、「Cloud API キーの数」を参照してください。正しい認証ヘッダーがない API リクエストは失敗します。キーは、単一の Confluent クラスターへのアクセスを許可します。

API キーはユーザーまたはサービスアカウントを認証するために使用される認証情報であるため、API キーを使用する際に適用される権限はユーザーまたはサービスアカウントのものです。API キーは多くの権限を付与するため、これを GitHub やクライアント側のコードなどで一般公開しないでください。

HTTP 基本認証では、コロンで区切られ base-64 でエンコードされたキーを要求します。

たとえば、API キーが abcp7DEFGH123456789 で、対応するシークレットが XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO である場合は、MacOS または Linux 上で以下のコマンドを使用して、base-64 でエンコードされたヘッダーを生成します。

echo -n "abcp7DEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64

生成される認可ヘッダーを以下に示します。

Authorization: Basic QUJDREVGR0gxMjM0NTY3ODk6WE5DSVc5M0kyTDFTUVBKU0o4MjNLMUxTOTAyS0xERk1DWlBXRU8=

または、Postman などのツールを使ってテストする場合は、API キーをユーザー名、API シークレットをパスワードとして指定します。これで、Postman によりエンコードされます。

クラスターのリスト表示

Confluent Cloud 環境に対する Operator または Admin のアクセス許可が付与されている場合は、クラスターエンドポイントへの GET 呼び出しで、すべての Kafka クラスターのリストを表示できます。

リクエストでは、クラスターが含まれている環境の ID を指定する必要があり、追加のパラメーターは任意で指定します。プライベートネットワークのクラスターを呼び出す場合は、ネットワークの ID を指定する必要があります。API を使用したネットワークの作成の詳細については、ネットワーク API のリファレンス を参照してください。この呼び出しではペイロードは必要ありません。API キーと API シークレットが指定された認可ヘッダーが含まれていることを確認してください。

リクエストの例

次の例では、クラスターを一覧表示する方法を示しています。リクエストに以下のクエリパラメーターを含めることができます。

GET /cmk/v2/clusters?environment={environment_id}&page_size={page_size}&page_token={token}

リクエストに含めることができるクエリパラメーターは次のとおりです。

パラメーター 必須か省略可能か 説明
environment 必須 一覧表示するクラスターが含まれる環境の ID を指定します。
page_size 省略可能 返されるペイロードのページサイズを整数で指定します。最大値は 100、デフォルト値は 10 です。
spec.network プライベートネットワークの場合は必須 一覧表示するクラスターのネットワーク ID。クエリに複数のネットワーク ID を含めることができます。
page_token 省略可能 opaque ページネーショントークン文字列を含みます。

応答の例

呼び出しに成功すると、HTTP 200 OK と、その環境のクラスターのリストを含む JSON ペイロードが返されます。応答では、各クラスターについて以下の情報が含まれています。

  • クラスターのクラウドプロバイダー（AWS、GCP、AZURE）とリージョン。リージョンの一覧については「クラウドプロバイダーとリージョン」を参照してください。
  • クラスターのステータス（PROVISIONED、PROVISIONING、FAILED）と種類（ベーシック、スタンダード、専用）。
  • クラスターを含む環境についての情報。
  • 専用クラスターのみ - クラスターに割り当てられた CKU の数。
HTTP/1.1 200 OK
Content-Type: application/json

{
   "api_version": "cmk/v2",
   "data": [
       {
       "api_version": "cmk/v2",
       "kind": "Cluster",
       "id": "abc-f3a90de",
       "metadata": {
           "self": "https://api.confluent.cloud/v2/kafka-clusters/abc-f3a90de",
           "resource_name": "crn://confluent.cloud/kafka=abc-f3a90de",
           "created_at": "2022-04-22T20:45:26.657894Z",
           "updated_at": "2022-04-22T21:13:55.742641944Z"
       },
       "spec": {
           "display_name": "ProdKafkaCluster",
           "availability": "SINGLE_ZONE",
           "cloud": "GCP",
           "region": "us-east4",
           "config": {
               "kind": "Basic"
           },
           "kafka_bootstrap_endpoint": "abc-00000-00000.us-east4.gcp.glb.confluent.cloud:9092",
           "http_endpoint": "https://abc-00000-00000.us-east4.gcp.glb.confluent.cloud",
           "environment": {
            "id": "env-00000",
            "related": "https://api.confluent.cloud/v2/environments/env-00000",
            "resource_name": "crn://confluent.cloud/organization=1234abcd-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000",
            "api_version": "org/v2",
            "kind": "Environment"
           }
       },
       "status": {
           "phase": "PROVISIONED"
       }
     }
   ],
   "kind": "ClusterList",
   "metadata": {
     "first": "https://api.confluent.cloud/cmk/v2/clusters",
     "total_size": 1
   }
}

呼び出しが失敗したときに受け取る応答のタイプの詳細については、「失敗」を参照してください。

クラスターの作成

Confluent Cloud 環境に対する Operator または Admin のアクセス許可が付与されている場合は、クラスターエンドポイントへの POST 呼び出しで、Kafka クラスターを作成できます。「Confluent Cloud のサービスクォータ」を順守する必要があることに注意してください。また、API キーと API シークレットが指定された認可ヘッダーが含まれていることを確認してください。

専用クラスターの場合、追加のオプションが 2 つあります。

POST /cmk/v2/clusters

リクエスト（すべてのクラスタータイプ）

リクエストを実行する際には、以下を指定した spec オブジェクトを含む JSON ペイロードを含めます。

パラメーター 必須か省略可能か 説明
display_name 必須 クラスターの表示名。
availability 必須 クラスターのアベイラビリティ: SINGLE_ZONE または MULTI_ZONE。
cloud 必須 GCP、AZURE、または AWS
region 必須 クラウドプロバイダーの有効なリージョン。リストについては「クラウドプロバイダーとリージョン」を参照してください。
config 必須 クラスタータイプ（kind: Basic、Standard、Dedicated）を含むオブジェクト。専用クラスターの場合、cku も整数値で指定する必要があります。また、任意で BYOK クラスターの encryption_key を指定することもできます。「セルフマネージド型キーを使用した Confluent Cloud クラスターの暗号化」を参照してください。クラスターはベーシックからスタンダードにアップグレードすることはできますが、スタンダードからベーシックにダウングレードすることはできません。
environment 必須 環境 ID（id: env-1234）を含むオブジェクト。
network プライベートネットワークの場合は必須 ネットワーク ID（id: n-12345）と関連する環境名を含むオブジェクト。

以下は、スタンダードクラスターおよびベーシッククラスターのリクエストフォーマットの例です。

POST /cmk/v2/clusters HTTP/1.1
Host: api.confluent.cloud

{
   "spec":{
       "display_name":"ProdKafkaCluster",
       "availability":"SINGLE_ZONE",
       "cloud":"GCP",
       "region":"us-east4",
       "config":{
           "kind":"Basic"
       },
       "environment":{
           "id":"env-00000"
       }
   }
}

応答の例

成功した場合は、HTTP 202 ACCEPTED と、クラスターの説明を含む JSON ペイロードが返されます。クラスターの説明には以下が含まれます。

  • クラスターのクラウドプロバイダー（AWS、GCP、AZURE）とリージョン。リージョンの一覧については「クラウドプロバイダーとリージョン」を参照してください。
  • クラスターのステータス（PROVISIONED、PROVISIONING、FAILED）と種類（ベーシック、スタンダード、専用）。
  • クラスターを含む環境についての情報。
  • 専用クラスターのみ - クラスターに割り当てられた CKU の数と、プライベートネットワークの場合はネットワーク ID。

スタンダードおよびベーシッククラスターの応答の例:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
       "api_version": "cmk/v2",
       "id": "abc-f3a90de",
       "kind": "Cluster",
       "metadata": {
           "created_at": "2022-04-22T20:45:26.657894Z",
           "self": "https://api.confluent.cloud/v2/kafka-clusters/abc-f3a90de",
           "resource_name": "crn://confluent.cloud/kafka=abc-f3a90de",
           "updated_at": "2022-04-22T20:45:26.659364Z"
       },
       "spec": {
           "display_name": "ProdKafkaCluster",
           "availability": "SINGLE_ZONE",
           "cloud": "GCP",
           "region": "us-east4",
           "config": {
               "kind": "Basic"
           },
           "kafka_bootstrap_endpoint": "abc-00000-00000.us-east4.gcp.glb.confluent.cloud:9092",
           "http_endpoint": "https://abc-00000-00000.us-east4.gcp.glb.confluent.cloud",
           "environment": {
             "api_version": "org/v2",
             "id": "env-00000",
             "kind":"Environment"
             "related": "https://api.confluent.cloud/v2/environments/env-00000",
             "resource_name": "crn://confluent.cloud/organization=1234abcd-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
           }
       },
       "status": {
           "phase": "PROVISIONING"
       }
}

呼び出しが失敗したときに受け取る応答のタイプの詳細については、「失敗」を参照してください。

クラスターの読み取り

Confluent Cloud 環境に対する Operator または Admin のアクセス許可が付与されている場合は、クラスターエンドポイントへの GET 呼び出しで、指定したクラスターの詳細情報を取得できます。リクエストでは、環境 ID およびクラスター ID を指定する必要があります。この呼び出しではペイロードは必要ありません。API キーと API シークレットが指定された認可ヘッダーが含まれていることを確認してください。

リクエストの例（すべてのクラスタータイプ）

GET /cmk/v2/clusters/{id}?environment={environment_id}

リクエストには以下のパラメーターを含める必要があります。

パラメーター 必須か省略可能か 説明
id 必須 読み取るクラスターの ID を指定するパスパラメーター。
environment 必須 読み取るクラスターが含まれる環境の ID を指定するクエリパラメーター。

応答の例

成功した場合は、HTTP 200 OK と、クラスターについて以下のような説明を含む JSON ペイロードが返されます。

  • クラスターのクラウドプロバイダー（AWS、GCP、AZURE）とリージョン。リージョンの一覧については「クラウドプロバイダーとリージョン」を参照してください。
  • クラスターのステータス（PROVISIONED、PROVISIONING、FAILED）と種類（ベーシック、スタンダード、専用）。
  • クラスターを含む環境についての情報。
  • 専用クラスターのみ - クラスターに割り当てられた CKU の数。

スタンダードおよびベーシッククラスターの応答の例:

HTTP/1.1 200 OK
Content-Type: application/json

{
       "api_version":"cmk/v2",
       "kind":"Cluster",
       "id":"abc-f3a90de",
       "metadata":{
           "self":"https://api.confluent.cloud/v2/kafka-clusters/abc-f3a90de",
           "resource_name":"crn://confluent.cloud/kafka=abc-f3a90de",
           "created_at":"2022-04-22T20:45:26.657894Z",
           "updated_at":"2022-04-22T20:45:28.045579Z"
       },
       "spec":{
           "display_name":"ProdKafkaCluster",
           "availability":"SINGLE_ZONE",
           "cloud":"GCP",
           "region":"us-east4",
           "config":{
               "kind":"Standard"
           },
           "kafka_bootstrap_endpoint":"abc-00000-00000.us-east4.gcp.glb.confluent.cloud:9092",
           "http_endpoint":"https://abc-00000-00000.us-east4.gcp.glb.confluent.cloud",
           "environment":{
               "api_version": "org/v2",
               "id": "env-00000",
               "kind": "Environment",
               "related":"https://api.confluent.cloud/v2/environments/env-00000",
               "resource_name":"crn://confluent.cloud/organization=abcd41c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
           }
       },
       "status":{
           "phase":"PROVISIONED"
       }
}

呼び出しが失敗したときに受け取る応答のタイプの詳細については、「失敗」を参照してください。

クラスターのアップデート

Confluent Cloud 環境に対する Operator または Admin のアクセス許可が付与されている場合は、クラスターエンドポイントへの HTTP PATCH 呼び出しでクラスターをアップデートできます。リクエストで環境 ID およびクラスター ID を指定し、変更の詳細を含むペイロードを含めます。このリクエストでは 1 つの変更を指定できます。

  • クラスタータイプの変更
  • クラスター名のアップデート
  • クラスターの CKU 数の 拡張 または 縮小 （専用クラスターのみ）

API キーと API シークレットが指定された認可ヘッダーが含まれていることを確認してください。

リクエストの例（すべてのクラスタータイプ）

PATCH /cmk/v2/clusters/{id}?environment={environment_id}
パラメーター 必須か省略可能か 説明
id 必須 アップデートするクラスターの ID を指定するパスパラメーター。
environment 必須 アップデートするクラスターが含まれる環境の ID を指定するクエリパラメーター。

JSON ペイロードには、以下を含む spec オブジェクトが含まれます。

  • 環境の ID を含む環境オブジェクト

次のいずれか 1 つ:

  • クラスターの新しい名前の値を提供する display_name プロパティ。
  • 目的のクラスタータイプ（ベーシック、スタンダード、専用）を指定する、kind プロパティを含む config オブジェクト。クラスターはベーシックからスタンダードにアップグレードすることはできますが、スタンダードからベーシックにダウングレードすることはできません。スタンダードクラスターに対してベーシックを指定すると、エラーが発生します。
  • 専用クラスターの場合のみ: cku の値を指定する config オブジェクト。縮小の操作の場合、クラスターから一度に削減できる CKU は 1 つです。

display_name または config オブジェクトのいずれか一方を含めます。両方を含めることはできません。

PATCH /cmk/v2/clusters/abc-f3a90de?environment=env-00000 HTTP/1.1
Host: api.confluent.cloud

{
   "spec": {
           "display_name": "updated_name",
           "environment": {
               "id": "env-00000""
           }
   }
 }

応答の例

成功した場合は、200 OK と、アップデートされたクラスターの説明を含む JSON ペイロードが返されます。他の呼び出しと同じように、ペイロードには以下が含まれます。

  • クラスターのクラウドプロバイダー（AWS、GCP、AZURE）とリージョン。リージョンの一覧については「クラウドプロバイダーとリージョン」を参照してください。
  • クラスターのステータス（PROVISIONED、PROVISIONING、FAILED）と種類（ベーシック、スタンダード、専用）。
  • クラスターを含む環境についての情報。
  • 専用クラスターのみ - クラスターに割り当てられた CKU の数。

スタンダードおよびベーシッククラスターの応答の例:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "api_version":"cmk/v2",
   "kind":"Cluster",
   "id":"abc-f3a90de",
   "metadata":{
       "self":"https://api.confluent.cloud/v2/kafka-clusters/abc-f3a90de",
       "resource_name":"crn://confluent.cloud/kafka=abc-f3a90de",
       "created_at": "2022-04-22T20:45:26.657894Z",
       "updated_at": "2022-04-22T21:13:55.742641944Z"
   },
   "spec":{
       "display_name":"updated_name",
       "availability":"SINGLE_ZONE",
       "cloud":"GCP",
       "region":"us-east4",
       "config":{
           "kind":"Standard"
       },
       "kafka_bootstrap_endpoint":"abc-00000-00000.us-east4.gcp.glb.confluent.cloud:9092",
       "http_endpoint":"https://abc-00000-00000.us-east4.gcp.glb.confluent.cloud",
       "environment":{
           "id":"env-00000",
           "related":"https://api.confluent.cloud/v2/environments/env-00000",
           "resource_name":"crn://confluent.cloud/organization=abcd41c4-edef-46ac-8a41-c49e44a3fd9a/environment=env-00000"
       }
   },
   "status":{
       "phase":"PROVISIONED"
   }
}

呼び出しが失敗したときに受け取る応答のタイプの詳細については、「失敗」を参照してください。

クラスターの削除

Confluent Cloud 環境に対する Operator または Admin のアクセス許可が付与されている場合は、クラスターエンドポイントへの DELETE 呼び出しで、Kafka クラスターを削除できます。リクエストで環境 ID およびクラスター ID を指定します。この呼び出しにはペイロードは不要です。API キーと API シークレットが指定された認可ヘッダーが含まれていることを確認してください。

リクエストの例（すべてのクラスタータイプ）

DELETE /cmk/v2/clusters/{id}?environment={environment_id}
パラメーター 必須か省略可能か 説明
id 必須 削除するクラスターの ID を指定するパスパラメーター。
environment 必須 削除するクラスターが含まれる環境の ID を指定するクエリパラメーター。

応答の例

成功した場合は、HTTP 204 No Content が返されます。

呼び出しが失敗したときに受け取る応答のタイプの詳細については、「失敗」を参照してください。

失敗

失敗した場合は、以下のいずれかのステータスを受け取ります。

400 Bad Request
通常は、形式に誤りがあるかパラメーターが不足しています。専用クラスターの場合、一度に 2 つ以上の CKU の削減を試みた場合に返されます。
401 Unauthorized
通常は、認証情報が無効であるか不足しています。
403 Forbidden
指定された認証情報がリソースに対して有効でないことを示します。クラスター ID と環境 ID が正しく、指定された認証情報と一致することを確認してください。
404 Not Found
指定された URL でリソースが見つからないことを示します。
429 Rate Limit Exceeded
送信したリクエスト数が多すぎます。
500 Oops something went wrong
他のエラーに該当しない問題が発生しています。

失敗メッセージの本文には、失敗した理由の詳細と、問題解決が必要な場合に Confluent サポートに伝える ID が含まれています。以下は、400 Bad Request エラーの例で、呼び出しが失敗した理由が含まれています。

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "errors": [
      {
           "id": "c9cb03c2878ca172bbd0072bd99a9aaa",
            "status": "400",
            "code": "parameter_missing",
            "detail": "Missing Parameter",
            "source": {
               "parameter": "environment"
             }
      }
   ]
 }

関連コンテンツ