A OpenAPI é uma especificação para descrever APIs REST. Com a especificação OpenAPI 2.0 (em inglês), é possível criar documentos da OpenAPI para as APIs Business Messages e Business Communications para descrever a estrutura delas.
Isso permite que você faça o seguinte:
- Criar bibliotecas de cliente na linguagem de sua preferência
- Criar stubs de servidor
- Usar ferramentas de gestão de APIs
Estrutura básica de um documento do OpenAPI
Um documento da OpenAPI descreve a superfície de uma API REST. O documento define o nome e a descrição da API, os endpoints individuais (caminhos) na API, como os autores das chamadas são autenticados e muito mais.
Clique abaixo para ver um exemplo dessa estrutura básica.
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"
}
}
}
}
}
}
Para saber mais sobre a estrutura de um documento da OpenAPI, consulte o site do Swagger (em inglês).
Como acessar os documentos da OpenAPI
Para acessar os documentos da OpenAPI, você precisa ter uma chave de API de um projeto do Google Cloud Platform (GCP) com as APIs Business Messages e Business Communications ativadas.
Siga as seções abaixo para
- crie um projeto do GCP
- criará uma Chave de API
- Ativar a API Business Messages e a API Business Communications
Depois de concluir essas etapas, acesse os documentos da OpenAPI.
Criar um projeto do GCP
Se você já tiver um projeto do GCP, use-o para criar uma chave de API.
Para criar um novo projeto do GCP, faça o seguinte:
- Navegue até a página Gerenciar recursos no Console do GCP.
- Na lista suspensa Selecionar organização, na parte superior da página, escolha a organização para a qual você quer criar o projeto. Se você for um usuário de teste sem custo financeiro, pule esta etapa.
- Clique em Criar projeto.
- Na janela Novo projeto, insira o nome de um projeto e selecione uma conta de faturamento, conforme aplicável. O nome de um projeto só pode ser composto por letras, números, aspas simples, hifens, espaços ou pontos de exclamação e precisa ter entre 4 e 30 caracteres.
Em Local, insira a organização ou pasta pai do novo projeto.
Clique em Criar.
crie uma chave de API
Acesse a página Credenciais no Console do GCP.
Clique em Criar credenciais e selecione Chave de API.
A chave recém-criada será exibida na caixa de diálogo Chave de API criada. Copie a chave e a mantenha em segurança. Para saber mais sobre as chaves de API, consulte a documentação delas.
Ativar as APIs Business Communications e Business Messages
Para ativar essas APIs no projeto do GCP, faça o seguinte:
- Acesse a página APIs e serviços no Console do GCP.
- Na lista suspensa Selecionar projeto, escolha o projeto em que você quer ativar as APIs.
- Clique em Ativar APIs e serviços.
- No campo Pesquisar APIs e serviços, digite Business Messages.
- Selecione API Business Messages.
- Selecione Ativar.
- Clique em Ativar APIs e serviços.
- No campo Pesquisar APIs e serviços, insira Business Communications.
- Selecione a API Business Communications.
- Selecione Ativar.
Agora sua chave de API tem permissão para acessar os documentos da OpenAPI nas APIs Business Messages e Business Communications.
Acessar os documentos da OpenAPI
Execute este comando para acessar o documento da OpenAPI na API Business Messages:
curl "https://businessmessages.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"
Execute este comando para acessar o documento da OpenAPI para a API Business Communications:
curl "https://businesscommunications.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"
Substitua API_KEY pela sua chave de API.