OpenAPI は、REST API を記述するための仕様です。OpenAPI 仕様 2.0 を使用すると、Business Messages API と Business Communications API の OpenAPI ドキュメントを作成し、その構造を記述できます。
これにより、次のことが可能になります。
- 任意の言語でクライアント ライブラリを作成
- サーバースタブを作成する
- API 管理ツールを使用する
OpenAPI ドキュメントの基本構造
OpenAPI ドキュメントは REST API のサーフェスについて記述しています。このドキュメントでは、API の名前と説明、API の個々のエンドポイント（パス）、呼び出し元の認証方法などを定義します。
以下に、この基本的な構造の例を示します。
JSON
{
"swagger": "2.0",
"host": "businessmessages.googleapis.com",
"info": {
"title": "Business Messages API",
"description": "",
"version": "v1"
},
"paths": {
"/v1/conversations/{conversationsId}/messages": {
"post": {
"description": "Sends a message from an agent to a user.",
"parameters": [
{
"description": "Part of `parent`. Required. The conversation that contains the message. Resolves to \"conversations/{conversationId}\".",
"type": "string",
"in": "path",
"required": true,
"name": "conversationsId"
},
{
"description": "Optional. A flag to send the specified fallback text instead of other message content.",
"name": "forceFallback",
"type": "boolean",
"in": "query"
},
{
"name": "message",
"schema": {
"$ref": "#/definitions/BusinessMessagesMessage"
},
"in": "body",
"description": "Required. The content of a message."
}
],
"tags": [
"businessmessages"
],
"operationId": "CreateMessage",
"responses": {
"default": {
"schema": {
"$ref": "#/definitions/BusinessMessagesMessage"
},
"description": "Successful operation"
}
}
}
}
}
}
OpenAPI ドキュメントの構造の詳細については、Swagger のウェブサイトをご覧ください。
OpenAPI ドキュメントにアクセスする方法
OpenAPI ドキュメントにアクセスするには、Business Messages API と Business Communications API が有効になっている Google Cloud Platform（GCP）プロジェクトの API キーが必要です。
以下のセクションに沿って、
- GCP プロジェクトを作成する
- API キーの作成
- Business Messages API と Business Communications API を有効にします
これらの手順を完了すると、OpenAPI ドキュメントにアクセスできます。
GCP プロジェクトを作成する
すでに GCP プロジェクトがある場合は、それを使用して API キーを作成できます。
新しい GCP プロジェクトを作成する手順は次のとおりです。
- GCP Console の [リソースの管理] ページに移動します。
- ページの上部にある「組織の選択」プルダウン リストで、プロジェクトを作成する組織を選択します。無料トライアルをご利用の場合は、この手順をスキップできます。
- [プロジェクトの作成] をクリックします。
- [New Project] ウィンドウでプロジェクト名を入力し、該当する請求先アカウントを選択します。プロジェクト名には文字、数字、単一引用符、ハイフン、スペース、感嘆符のみを使用でき、4 ～ 30 文字にする必要があります。
[ロケーション] に、新しいプロジェクトの親組織またはフォルダを入力します。
[作成] をクリックします。
API キーを作成する
GCP Console の [認証情報] ページに移動します。
[認証情報を作成] をクリックし、[API キー] を選択します。
[API キーを作成しました] ダイアログ ボックスに、新たに作成されたキーが表示されます。キーをコピーして、安全な場所に保管してください。API キーの詳細については、API キーに関するドキュメントをご覧ください。
Business Communications API と Business Messages API の有効化
GCP プロジェクトでこれらの API を有効にする手順は次のとおりです。
- GCP Console の [API とサービス] ページに移動します。
- [プロジェクトを選択] プルダウン リストで、API を有効にするプロジェクトを選択します。
- [API とサービスの有効化] をクリックします。
- [API とサービスを検索] に「Business Messages」と入力します。
- [Business Messages API] を選択します。
- [有効にする] をクリックします。
- [API とサービスの有効化] をクリックします。
- [API とサービスを検索] に「Business Communications」と入力します。
- [Business Communications API] を選択します。
- [有効にする] をクリックします。
これで、API キーには Business Messages API と Business Communications API の OpenAPI ドキュメントにアクセスする権限が付与されました。
OpenAPI ドキュメントにアクセスする
Business Messages API の OpenAPI ドキュメントにアクセスするには、
curl "https://businessmessages.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"コマンドを実行します。
Business Communications API の OpenAPI ドキュメントにアクセスするには、次のコマンドを実行します。
curl "https://businesscommunications.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"
API_KEY は、API キーに置き換えます。