バージョン: 3.5 Stable

概要

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

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

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

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

始める前に

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

PhoenixAI Cloud アカウントを持っていること。
curl または Postman などのウェブ開発ツールをインストールしていること。
アクセストークンを取得する。
(オプション) クラスター ID を取得する。

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

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

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

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

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

PhoenixAI Cloud コンソールにサインインします。
左側のナビゲーションペインで、Application keys を選択します。
Application keys ページで、New secret をクリックします。
表示されるダイアログボックスで、オプションで説明を入力し、Generate をクリックしてアプリケーションキーを生成します。その後、ダイアログボックスを閉じる前に Secret と Client ID をコピーします。

注意

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

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

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

PhoenixAI Cloud コンソールにサインインします。
左側のナビゲーションペインで、Access Control > Member を選択します。
Members ページで、Service accounts タブをクリックします。
Service accounts タブで、Create a service account をクリックします。
Generate secret for service account ダイアログボックスで、サービスアカウントの名前を入力し、Generate now をクリックします。
Client Secret と Client ID をコピーし、ダイアログボックスを閉じるために Yes, I have finished it をクリックします。

注意

Client Secret はサービスアカウントが作成されたときにのみ表示されます。ダイアログボックスを閉じる前に Client Secret をコピーして保存してください。
サービスアカウントの詳細ページで、Granted roles タブをクリックします。
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 コールでは、クエリしたい PhoenixAI クラスターの ID を提供する必要があります。クラスター ID を取得するには、以下の手順に従ってください：

PhoenixAI Cloud コンソールにサインインします。
左側のナビゲーションペインで、Clusters を選択します。
表示されるページで、クエリしたいクラスターをクリックします。
クラスター詳細ページの 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
            }
        ]
    }
}

始める前に​

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

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

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

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

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

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

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

API コールを行う​

API コールを構築する​

レスポンスを確認する​