OpenAPI 是用來說明 REST API 的規格。使用 OpenAPI 規格 2.0，您可以為 Business Messages 和 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 和 Business Communications API 的 Google Cloud Platform (GCP) 專案。
請參閱下列各節，以
- 建立 GCP 專案
- 建立 API 金鑰
- 啟用 Business Messages API 和 Business Communications API
完成這些步驟後，您可以存取 OpenAPI 文件。
建立 GCP 專案
如果您已有 GCP 專案，可以使用該專案建立 API 金鑰。
如要建立新的 GCP 專案，請按照下列指示操作：
- 前往 GCP 控制台的「Manage resources」(管理資源) 頁面。
- 在頁面頂端的「選取機構」下拉式清單中，選取您要建立專案的機構。如果您是免費試用使用者，請略過此步驟。
- 按一下 [建立專案]。
- 在「新增專案」視窗中輸入專案名稱，然後選取適當的帳單帳戶。專案名稱只能包含字母、數字、單引號、連字號、空格或驚嘆號，且長度必須介於 4 至 30 個字元。
針對「Location」(位置)，輸入新專案的上層機構或資料夾。
點選「建立」。
建立 API 金鑰
前往 GCP 控制台的「憑證」頁面。
按一下 [Create credentials] (建立憑證)，然後選取 [API key] (API 金鑰)。
「建立的 API 金鑰」對話方塊會顯示您新建立的金鑰。 請妥善保管並妥善保管金鑰。如要進一步瞭解 API 金鑰，請參閱 API 金鑰說明文件。
啟用 Business Communications API 和 Business Messages API
如要在 GCP 專案中啟用這些 API，請按照下列指示操作：
- 前往 GCP 控制台的「API 和服務」頁面。
- 在 [選取專案] 下拉式清單中，選取您要啟用 API 的專案。
- 點選「啟用 API 和服務」。
- 在 [搜尋 API 和服務] 欄位中輸入 Business Messages。
- 選取 [Business Messages API]。
- 按一下「啟用」。
- 點選「啟用 API 和服務」。
- 在「搜尋 API 和服務」欄位中輸入 Business Communications。
- 選取 [Business Communications API]。
- 按一下「啟用」。
現在，您的 API 金鑰具備存取 Business Messages 和 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 金鑰。