本記事では、HTTPを使用する方法について説明し、OceanBaseクラスタ情報を照会するインターフェース呼び出しを例に、obshellのオープンAPIの呼び出し方を紹介します。
リクエスト構造
完全なHTTPリクエストには、リクエストURI、リクエストメソッド、リクエストヘッダー、および リクエストボディ が含まれます。
リクエストURI
リクエストURIは以下の部分で構成されます：
{scheme}://{endpoint}/{resource-path}?{query-string}
フィールド |
説明 |
|---|---|
| scheme | トランスポートプロトコルを指定します。通常は HTTP または HTTPS です。 |
| endpoint | obshellのサービスアドレスを指定します。例：10.10.10.1:2886。具体的なデプロイによって決まります。 |
| resource-path | インターフェースのリソースパスです。各インターフェースのリソースパスについては、対応するインターフェースドキュメントの リクエストパス のセクションを参照してください。例えば、OceanBaseクラスタ情報を照会するリソースパスは /api/v1/ob/info です。 |
| query-string | クエリパラメータ。オプションです。a=10&b=hello のように、複数のキーと値のペアで構成されます。query-string と resource-path の間は ? で区切ります。 |
obshellのサービスアドレスを 10.10.10.1:2886 として例にすると、OceanBaseクラスタ情報の照会 を完全に示すリクエストURIの例は次のとおりです：
http://10.10.10.1:2886/api/v1/ob/info
リクエストメソッド
HTTPプロトコルのメソッドであり、GET、PUT、POST、DELETEが含まれます。各インターフェースのドキュメントでは、そのインターフェースのリクエストメソッドについて詳しく説明されています。例えば、OceanBaseクラスタ情報を照会するリクエストパスが GET /api/v1/ob/info の場合、そのインターフェースのリクエストメソッドは GET であることを意味します。
リクエストヘッダー
認証情報など、リクエストの追加情報を含みます。
プロパティ |
必須 |
説明 |
例 |
|---|---|---|---|
| Content-Type | はい | メッセージボディのタイプです。obshellは一貫してapplication/jsonタイプのメッセージボディを使用します。 |
application/json |
認証の説明
詳細については、APIハイブリッド暗号化を参照してください。
戻り値構造
オープンAPIが返すデータは、統一されたデータ構造を使用します（個別の特別なインターフェースを除く）。基本的な戻り結果のデータ構造は以下のとおりです：
パラメータ |
型 |
説明 |
|---|---|---|
| data | any | 複合データ型 |
| error | ApiError | リクエストによって生成されたError。以下の情報を含みます：
|
| successful | bool | リクエストが成功したかどうか |
| timestamp | time.Time | サーバーがリクエストを完了したタイムスタンプ |
| duration | int | サーバーがリクエストを処理した時間（ミリ秒） |
| status | int | HTTP Status仕様に準拠したコード |
| traceId | string | リクエストのTrace ID |
呼び出し例
curlツールを使用してオープンAPIのインターフェースを呼び出すことができます。以下の例では、obshellアプリケーションのアドレスは 10.10.10.1、ポートは 2886 です。アクセスするインターフェースは、指定されたノードの削除です。ここで、${encrypted_header} は暗号化されたHeaderの内容を指し、${encrypted_body} は暗号化されたリクエストボディの内容を指します。具体的な生成方法については、APIハイブリッド暗号化を参照してください。
curl "http://10.10.10.1:2886/api/v1/agent/remove"
-H "Content-Type: application/json"
-H 'X-OCS-Header:${encrypted_header}'
-X POST
-d '${encrypted_body}'