OpenAPI è una specifica per la descrizione delle API REST. Utilizzando la specifica OpenAPI 2.0, puoi creare documenti OpenAPI per le API Business Messages e Business Communications per descrivere la loro struttura.
In questo modo, puoi:
- Crea librerie client nella lingua che preferisci
- Crea stub server
- Utilizzare gli strumenti di gestione delle API
Struttura di base di un documento OpenAPI
Un documento OpenAPI descrive la superficie di un'API REST. Il documento definisce il nome e la descrizione dell'API, i singoli endpoint (percorsi) dell'API, il modo in cui i chiamanti sono autenticati e altro ancora.
Fai clic di seguito per visualizzare un esempio di questa struttura di base.
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"
}
}
}
}
}
}
Per scoprire di più sulla struttura di un documento OpenAPI, visita il sito web di Swagger.
Come accedere ai documenti OpenAPI
Per accedere ai documenti OpenAPI, devi avere una chiave API di un progetto Google Cloud Platform (GCP) con le API Business Messages e Business Communications attivate.
Segui le sezioni seguenti per
- crea un progetto GCP
- crea una chiave API
- abilita l'API Business Messages e l'API Business Communications
Una volta completati questi passaggi, puoi accedere ai documenti OpenAPI.
Creare un progetto Google Cloud
Se hai già un progetto GCP, puoi utilizzarlo per creare una chiave API.
Per creare un nuovo progetto GCP, segui questi passaggi:
- Vai alla pagina Gestisci risorse nella console di GCP.
- Nell'elenco a discesa Seleziona organizzazione nella parte superiore della pagina, scegli l'organizzazione per cui vuoi creare il progetto. Se stai usufruendo di una prova senza costi, salta questo passaggio.
- Fai clic su Crea progetto.
- Nella finestra Nuovo progetto, inserisci un nome per il progetto e seleziona un account di fatturazione appropriato. Il nome del progetto può contenere solo lettere, numeri, virgolette singole, trattini, spazi o punti esclamativi e deve avere una lunghezza compresa tra 4 e 30 caratteri.
In Posizione, inserisci la cartella o l'organizzazione padre per il nuovo progetto.
Fai clic su Crea.
Crea una chiave API
Vai alla pagina Credenziali nella console di GCP.
Fai clic su Crea credenziali, quindi seleziona Chiave API.
Nella finestra di dialogo Chiave API creata viene visualizzata la chiave appena creata. Copia la chiave e tienila al sicuro. Per scoprire di più sulle chiavi API, consulta la documentazione relativa alle chiavi API.
Abilita le API Business Communications e Business Messages
Per attivare queste API nel tuo progetto GCP, segui questi passaggi:
- Vai alla pagina API e servizi nella console di GCP.
- Nell'elenco a discesa Seleziona progetto, seleziona il progetto per cui attivare le API.
- Fai clic su Abilita API e servizi.
- Nel campo Cerca API e servizi, inserisci Business Messages.
- Seleziona l'API Business Messages.
- Fai clic su Abilita.
- Fai clic su Abilita API e servizi.
- Nel campo Cerca API e servizi, inserisci Comunicazioni aziendali.
- Seleziona l'API Business Communications.
- Fai clic su Abilita.
Ora la chiave API dispone delle autorizzazioni per accedere ai documenti OpenAPI per le API Business Messages e Business Communications.
Accedere ai documenti OpenAPI
Esegui questo comando per accedere al documento OpenAPI per l'API Business Messages:
curl "https://businessmessages.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"
Esegui questo comando per accedere al documento OpenAPI per l'API Business Communications:
curl "https://businesscommunications.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"
Sostituisci API_KEY con la chiave API.