メインコンテンツまでスキップ

概要

CelerData Cloud BYOC API は、CelerData Cloud 内の管理オブジェクトをプログラムで管理するための HTTPS ベースの RESTful インターフェースです。この API を使用すると、クラスターやウェアハウス（エラスティッククラスターにのみ利用可能）、使用状況、請求などのさまざまなリソースを安全に作成、管理、クエリできます。

この API には以下の機能があります：

  • JSON エンティティ。すべてのエンティティは JSON で表現されます。
  • HTTPS のみ。API には HTTPS 経由でのみアクセスできます。これにより、ネットワーク上で送信されるすべてのデータが TLS で暗号化されます。
  • OAuth 2.0 に準拠したクライアント資格情報ベースの認証。API にアクセスする前に、アプリケーションキーを生成するか、サービスアカウントを作成し、そのクライアント ID とシークレットキーを base64 エンコードされた文字列に変換し、その文字列を使用して API への認証を許可するアクセストークンを作成する必要があります。

このガイドでは、API を使用する前に必要な手順を紹介し、API コールを行うプロセスを説明します。

始める前に​

このガイドを完了するには、以下が必要です：

アクセストークンを取得する​

ステップ 1: クライアント ID とクライアントシークレットを生成する​

現在、CelerData Cloud BYOC はアプリケーションキーとサービスアカウントによる認証をサポートしています。

クライアント ID とクライアントシークレットを取得するために、アプリケーションキーを生成するか、サービスアカウントを作成することができます。

アプリケーションキーを生成する​

  1. CelerData Cloud BYOC コンソール にサインインします。

  2. 左側のナビゲーションペインで、Application keys を選択します。

  3. Application keys ページで、New secret をクリックします。

  4. 表示されるダイアログボックスで、オプションで説明を入力し、Generate をクリックしてアプリケーションキーを生成します。その後、ダイアログボックスを閉じる前に Secret と Client ID をコピーします。

    注意

    Secret はアプリケーションキーが作成されたときにのみ表示されます。ダイアログボックスを閉じる前に Secret をコピーして保存してください。

    アプリケーションキーを作成する

アプリケーションキーの管理に関する詳細は、Application keys を参照してください。

サービスアカウントを作成する​

  1. CelerData Cloud BYOC コンソール にサインインします。

  2. 左側のナビゲーションペインで、Access Control > Member を選択します。

  3. Members ページで、Service accounts タブをクリックします。

  4. Service accounts タブで、Create a service account をクリックします。

  5. Generate secret for service account ダイアログボックスで、サービスアカウントの名前を入力し、Generate now をクリックします。

  6. Client Secret と Client ID をコピーし、ダイアログボックスを閉じるために Yes, I have finished it をクリックします。

    注意

    Client Secret はサービスアカウントが作成されたときにのみ表示されます。ダイアログボックスを閉じる前に Client Secret をコピーして保存してください。

  7. サービスアカウントの詳細ページで、Granted roles タブをクリックします。

  8. Granted roles タブで、Assign new role ドロップダウンリストから割り当てたい役割を選択し、Assign をクリックします。

サービスアカウントの管理に関する詳細は、Service accounts を参照してください。

ステップ 2: base64 エンコードされた文字列を生成する​

以下のコマンドを使用して base64 エンコードされた文字列を生成します：

echo -n <client_id>:<secret> | base64 | tr -d "\n"

上記のコマンドで <client_id> と <secret> を、ステップ 1 で取得したクライアント ID とシークレットキーに置き換える必要があります。例：

echo -n 50292c3c-2b95-417f-880d-0c7e8c26eac1:YOklxY24RKgveikknUI48RuHnkPsFit1u0i2TGyp | base64 | tr -d "\n"

以下のような base64 エンコードされた文字列が返されます：

NTAyOTJjM2MtMmI5NS00MTdmLTg4MGQtMGM3ZThjMjZlYWMxOllPa2x4WTI0UktndmVpa2tuVUk0OFJ1SG5rUHNGaXQxdTBpMlRHeXA=

生成された base64 エンコードされた文字列は、アクセストークンを作成するための API コールを行う際に使用され、HTTP リクエストに Authorization: Basic base64(<client_id>:<secret>) ヘッダーとして追加されます。

ステップ 3: アクセストークンを作成する​

アクセストークンを作成するために API コールを行います。上記の ステップ 2 で生成された base64 エンコードされた <client_id>:<secret> 文字列を HTTP リクエストに Authorization: Basic base64(<client_id>:<secret>) ヘッダーとして追加する必要があります。詳細は Create access token を参照してください。

作成されたアクセストークンは、他の API コールを行う際に使用され、HTTP リクエストに Authorization: Bearer <access_token> ヘッダーとして追加されます。

(オプション) クラスター ID を取得する​

一部の API コールでは、クエリしたい CelerData クラスターの ID を提供する必要があります。クラスター ID を取得するには、以下の手順に従ってください：

  1. CelerData Cloud BYOC コンソール にサインインします。
  2. 左側のナビゲーションペインで、Clusters を選択します。
  3. 表示されるページで、クエリしたいクラスターをクリックします。
  4. クラスター詳細ページの Overview タブで、Cluster properties セクションに移動し、Cluster ID を見つけます。

API コールを行う​

このセクションでは、curl を例にして、クラスターの CCU 使用量を クエリする 方法を説明し、API コールを構築し、レスポンスを確認する方法を理解するのに役立てます。

API コールを構築する​

クラスター ID が 82964bc5-a8ce-4236-9fe6-1ad1e0f80e15 で、アクセストークンが NWM0MWU1NJGTZME1OC0ZZDNKLTK0MZKTODQXM2EXNGM3MTYX であると仮定します。

以下のコマンドをターミナルで実行して、2023年6月1日から2023年6月31日までの期間内のクラスターの CCU 使用量をクエリし、日ごとの CCU 使用量の詳細を表示します：

    curl --request GET \
  --url 'https://cloud-api.celerdata.com/api/1.0/usages/82964bc5-a8ce-4236-9fe6-1ad1e0f80e15?start_date=20230701&end_date=20230731&show_detail=true' \
  --header 'Authorization: Bearer NWM0MWU1NJGTZME1OC0ZZDNKLTK0MZKTODQXM2EXNGM3MTYX'

レスポンスを確認する​

API コールを送信した後、レスポンスのステータスコードが 20000 であり、クラスターの使用量の詳細が表示される場合、リクエストは成功しています。

レスポンスボディは以下の3つの部分で構成されています：

  • code: エラーコード。返されたエラーコードが 20000 の場合、リクエストは成功しました。他のエラーコードが返された場合、リクエストは失敗しました。
  • data: API コールの結果。data オブジェクトは一部の API アクションでは返されない場合があります。
  • message: エラーメッセージ。このフィールドは、返された code が 20000 でない場合にのみ返されます。リクエストが成功したか失敗したかを message の返り値に基づいて判断しないでください。

以下は、成功した API コールのレスポンスの例です：

{
    "code":20000,
    "data":{
        "cluster_id":"82964bc5-a8ce-4236-9fe6-1ad1e0f80e15",
        "cluster_name":"test_privilege_30-wybing",
        "total_usage":"87.025277",
        "details":[
            {
                "usage":"18.130654",
                "date":20230703
            }
        ]
    }
}