本記事では、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ツールを使用して、このOpen APIのインターフェースを呼び出すことができます。以下の例では、obshellアプリケーションへのアクセスアドレスは10.10.10.1、ポートは2886、アクセスするインターフェースは指定ノードの削除です。ここで、${encrypted_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}'