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 文档,您必须拥有 Google Cloud Platform (GCP) 项目中已启用 Business Messages 和 Business Communications API 的 API 密钥。
请按照以下部分操作,
- 创建 GCP 项目
- 创建 API 密钥
- 启用 Business Messages API 和 Business Communications API
完成这些步骤后,您就可以访问 OpenAPI 文档了。
创建 GCP 项目
如果您已有 GCP 项目,则可以使用它来创建 API 密钥。
如需创建新的 GCP 项目,请执行以下操作:
- 导航到 GCP 控制台中的管理资源页面。
- 在页面顶部的选择组织下拉列表中,选择要为其创建项目的组织。 如果您是免费试用用户,请跳过此步骤。
- 点击创建项目。
- 在新建项目窗口中,输入项目名称并选择适用的结算帐号。项目名称只能包含字母、数字、英文单引号、连字符、空格或英文感叹号,且长度必须介于 4 到 30 个字符之间。
对于位置,请输入新项目的父级组织或文件夹。
点击创建。
创建 API 密钥
导航到 GCP Console 中的“凭据”页面。
点击创建凭据,然后选择 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 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 密钥。