Ogni app Google Chat che crei richiede un proprio progetto Google Cloud con l'API Chat abilitata e configurata.
Per eseguire chiamate API di sola lettura con l'autenticazione utente, ad esempio per recuperare spazi ed elencare messaggi, devi solo attivare l'API e creare un client OAuth.
Per eseguire chiamate API di creazione, aggiornamento ed eliminazione o per eseguire il deployment e testare un'app di Chat interattiva (creata come componente aggiuntivo di Google Workspace che estende Chat), devi anche configurare l'API Chat. Le impostazioni di configurazione dell'API Chat consentono di specificare tutti i dettagli dell'app Chat, tra cui il nome visualizzato, l'avatar, gli endpoint di deployment e le funzionalità interattive.
Prerequisiti
- Un account Google Workspace Business o Enterprise con accesso a Google Chat.
- Crea un progetto Google Cloud.
- Configura la schermata per il consenso OAuth.
- Abilita l'API Google Chat.
Scegli un nome visualizzato, un avatar e una descrizione per la tua app di Chat
Quando attivi l'API Chat, configuri i dettagli dell'app di Chat che vengono visualizzati dagli utenti in Chat, tra cui un nome visualizzato, un avatar e una descrizione. Questi dettagli vengono visualizzati solo in Chat. Per pubblicare la tua app di Chat su Marketplace, devi anche specificare i dettagli che vengono visualizzati nella scheda di Marketplace dell'app di Chat.
Prima di configurare un'app di Chat, prepara le seguenti informazioni:
| Campo | Descrizione | Formato |
|---|---|---|
| Nome dell'app | Il nome visualizzato dell'app di Chat. | Fino a 25 caratteri alfanumerici |
| URL avatar | L'immagine visualizzata come avatar dell'app di Chat. | Un URL HTTPS che rimanda a un'immagine grafica quadrata (PNG o JPEG). Le dimensioni consigliate sono 256 x 256 pixel o superiori. |
| Descrizione | Una breve descrizione dell'app Chat, visualizzata quando gli utenti cercano app in Chat. | Fino a 40 caratteri alfanumerici |
| Descrizione lunga | Facoltativo. Una descrizione di ciò che l'app di Chat può fare, visualizzata quando gli utenti avviano una conversazione con l'app di Chat o aprono la home page delle sessioni per un agente. Al momento è supportato solo quando si aggiorna la configurazione dell'app utilizzando la console Google Cloud e non è supportato tramite l'API dei componenti aggiuntivi di Google Workspace. | Fino a 250 caratteri |
Il nome, l'avatar e la descrizione dell'app Chat vengono visualizzati dagli utenti nell'interfaccia utente di Chat. Per alcune richieste di scrittura dell'API Chat, Chat utilizza queste informazioni per attribuire le azioni eseguite da un'app di Chat in Chat.
Ad esempio, se chiami il metodo spaces.create(), Chat include il nome dell'app Chat nella descrizione di chi ha creato lo spazio, come mostrato nell'immagine seguente:
spaces.create() per creare uno
spazio per conto di un utente.
Per interagire con le app di Chat, gli utenti vedono o utilizzano queste informazioni anche nei seguenti modi:
- @menziona l'app di Chat per aggiungerla a uno spazio o inviarle un messaggio.
- Trova e avvia un messaggio diretto con l'app di Chat. Nel menu App, i messaggi diretti mostrano il nome e l'avatar dell'app di Chat.
- Dalla barra di scrittura, gli utenti possono sfogliare le app di Chat e visualizzarne il nome, l'avatar e la descrizione.
Configura l'app di Chat nella console Google Cloud
Una volta ottenuti i dettagli dell'app di Chat, apri il tuo progetto Cloud e configura l'API Chat:
Nella console Google Cloud, vai alla pagina API Chat e fai clic sulla pagina Configurazione:
In Informazioni sull'applicazione, compila i campi Nome app, URL avatar e Descrizione.
(Facoltativo) Compila il campo Descrizione lunga.
(Facoltativo) Dal menu Sintassi di markup, seleziona la sintassi di markup predefinita (Markdown o Chat) per i messaggi dell'app di Chat. Per scoprire di più sulla formattazione del testo e su come Chat determina la sintassi di markup per le richieste API, consulta Formattare i messaggi.
In Funzionalità interattive, configura se la tua app di Chat risponde alle interazioni degli utenti:
Per creare un'app di Chat interattiva, attiva Abilita funzionalità interattive e completa i seguenti passaggi:
- In Funzionalità:
- (Facoltativo) Seleziona Supporta la home dell'app per visualizzare una scheda della home page nella scheda Home dei messaggi diretti 1:1 con l'app Chat.
- Seleziona Partecipa a spazi e conversazioni di gruppo per rendere la tua app di Chat disponibile per l'installazione e l'utilizzo. Per impostazione predefinita, gli utenti possono installare l'app di Chat e scambiare messaggi con l'app di Chat in uno spazio dedicato tra l'utente e l'app di Chat. Gli utenti possono anche aggiungere l'app di Chat e interagire con l'app di Chat in spazi con più persone.
In Impostazioni di connessione, seleziona l'architettura che vuoi utilizzare per ricevere oggetti evento da Chat:
- Per utilizzare un servizio HTTP, seleziona URL endpoint HTTP e fornisci un URL.
- Per utilizzare un progetto Google Apps Script, seleziona Apps Script e fornisci un ID deployment per il progetto.
- Per utilizzare un agente Dialogflow, seleziona Dialogflow, seleziona Dialogflow CX o Dialogflow ES e fornisci il nome della risorsa dell'agente.
- Per utilizzare Pub/Sub, seleziona Cloud Pub/Sub e inserisci il nome dell'argomento.
(Facoltativo) Per indirizzare gli oggetti evento a endpoint o funzioni specifici, vai a Impostazioni di connessione > Trigger e fornisci o aggiorna gli endpoint o le funzioni di callback per i seguenti trigger di Chat:
- Home dell'app (se l'opzione Supporta la home dell'app è attiva): un utente apre la scheda Home in un messaggio diretto 1:1 con l'app Chat.
- Aggiunta allo spazio: un utente aggiunge l'app Chat a una conversazione di gruppo o a uno spazio oppure installa l'app Chat per i messaggi 1:1.
- Messaggio: un utente invia un messaggio all'app Chat. Ad esempio, un utente invia un messaggio diretto all'app Chat o @menziona l'app Chat in uno spazio con più persone.
- Rimosso dallo spazio: un utente disinstalla o rimuove l'app Chat da uno spazio.
- Comando dell'app: un utente richiama un comando rapido, un comando slash o un'azione di messaggio dall'app Chat.
(Facoltativo) Aggiungi altre funzionalità interattive, come sessioni, prompt iniziali, comandi (comandi rapidi, comandi slash e azioni sui messaggi) o anteprime dei link.
In Visibilità, seleziona Rendi disponibile l'app di Chat a utenti e gruppi specifici e inserisci gli indirizzi email di privati o di gruppi Google nella tua organizzazione Google Workspace:
- Per installare e testare la tua app, inserisci il tuo indirizzo email.
- Per condividere un'app di Chat interna con un team o con l'intera organizzazione senza pubblicarla nel Marketplace, inserisci uno o più gruppi Google. I gruppi non hanno un limite di membri. Se la tua app richiede ambiti
chat.app.*, devi comunque pubblicarla per l'approvazione dell'amministratore. - Se l'amministratore limita le installazioni di Marketplace alle app incluse in una lista consentita, la console Google Cloud limita questo campo a cinque indirizzi email di singoli utenti per lo sviluppo. La visibilità del gruppo viene applicata solo dopo che un amministratore ha aggiunto l'app alla lista consentita.
- In Funzionalità:
(Facoltativo) In Log, seleziona la casella di controllo Registra gli errori in Logging per utilizzare Google Cloud Logging. Per saperne di più, consulta Esegui query sui log degli errori per le app di Chat.
Fai clic su Salva.
Dopo aver salvato la configurazione, chiunque tu abbia specificato nell'impostazione Visibilità dell'API Chat può installare, testare o utilizzare l'app Chat. Per iniziare a testare ed eseguire il debug dell'app Chat, consulta Testa le funzionalità interattive per le app Google Chat.
Configura l'app di Chat utilizzando Google Cloud CLI
Anziché utilizzare la console Google Cloud, puoi visualizzare e aggiornare la configurazione di un'app di Chat dalla riga di comando con Google Cloud CLI (gcloud CLI). Ad esempio, puoi configurare un'app di Chat da uno script o conservare la sua configurazione in un file che memorizzi con il codice.
Il gruppo di comandi gcloud beta workspace-add-ons chat-app-config include i seguenti comandi:
describe: mostra la configurazione.update: configura un'app di Chat per la prima volta o ne modifica la configurazione.
I comandi utilizzano la risorsa chatAppConfig nell'API Google Workspace Add-ons.
Prima di iniziare
- Installa la gcloud CLI. Se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo
gcloud components update. Accedi a gcloud CLI con il tuo account utente. I comandi non supportano i service account.
gcloud auth loginImposta il progetto cloud della tua app di Chat come progetto predefinito di gcloud CLI. Utilizza l'ID progetto, perché i comandi non accettano un numero di progetto.
gcloud config set project PROJECT_IDIn alternativa, aggiungi il flag
--projecta ogni comando.Abilita l'API dei componenti aggiuntivi di Google Workspace nel progetto Cloud:
gcloud services enable gsuiteaddons.googleapis.comAssicurati di disporre dei seguenti ruoli Identity and Access Management (IAM) nel progetto Cloud:
- Sviluppatore di componenti aggiuntivi di Google Workspace
(
roles/gsuiteaddons.developer) per visualizzare e aggiornare la configurazione o Lettore di componenti aggiuntivi di Google Workspace (roles/gsuiteaddons.reader) per visualizzarla soltanto. Questi ruoli includono le autorizzazioni elencate in Prerequisiti e autenticazione. - Service Usage Consumer
(
roles/serviceusage.serviceUsageConsumer). gcloud CLI utilizza il progetto Cloud come progetto di quota per le sue richieste, il che richiede l'autorizzazioneserviceusage.services.use.
I ruoli Proprietario ed Editor includono tutte queste autorizzazioni. I ruoli Proprietario di app di Chat e Visualizzatore di app di Chat, che consentono di accedere alla pagina di configurazione nella console Google Cloud, non sono sufficienti.
- Sviluppatore di componenti aggiuntivi di Google Workspace
(
Visualizza la configurazione
Per visualizzare la configurazione dell'app di Chat, esegui il comando describe:
gcloud beta workspace-add-ons chat-app-config describeL'output è simile al seguente:
avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
allowlistedTestingPrincipals:
- user@example.com
appCommands:
- command: /help
commandId: 1
commandType: SLASH_COMMAND
description: Show available commands
connectionConfig:
httpEndpointConfig:
commonUrl: https://example.com/chat
supportsMultiuserSpaces: true
urlPatterns:
- hostPattern: example.com
pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE
Se il progetto cloud non ha ancora un'app di Chat, il comando viene eseguito correttamente e stampa solo il campo name della configurazione:
name: projects/123456789012/chatAppConfig
Per modificare l'output, aggiungi uno dei seguenti flag:
--format=json: stampa la configurazione in formato JSON.--view=basic: omette le impostazioni delle funzionalità interattive (interactiveFeatureConfig).--format="value(displayName)": stampa solo il nome visualizzato o una riga vuota se il progetto cloud non ha ancora un'app di Chat. Un'app di Chat configurata ha sempre un nome visualizzato, quindi puoi utilizzare questo flag in uno script per verificare se esiste un'app di Chat.
Aggiorna la configurazione
Per configurare un'app di Chat per la prima volta o per modificarne la configurazione, esegui il comando update. Specifica le impostazioni con i flag o in un file di configurazione. Non puoi combinare i due elementi in un unico comando.
La prima volta che esegui il comando per un progetto cloud, devi specificare almeno un nome visualizzato e una descrizione. A meno che non imposti lo stato su disattivato, l'app di Chat è attiva non appena il comando termina. Le persone che indichi come tester possono quindi trovarla e utilizzarla.
Utilizza i flag
L'esempio seguente configura un'app di Chat che riceve eventi in un endpoint HTTP:
gcloud beta workspace-add-ons chat-app-config update \
--display-name="Quickstart App" \
--description="Quickstart app" \
--avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
--http-endpoint-url=HTTP_ENDPOINT_URL \
--supports-multiuser-spaces \
--add-allowlisted-testing-principals=USER_EMAIL \
--error-logging-enabledSostituisci quanto segue:
HTTP_ENDPOINT_URL: l'URL HTTPS che riceve oggetti evento da Chat.USER_EMAIL: l'indirizzo email di una persona o di un gruppo della tua organizzazione Google Workspace che può installare e testare l'app Chat, ad esempio il tuo indirizzo email.
Il comando stampa la configurazione aggiornata.
La tabella seguente elenca i flag per le impostazioni nella pagina Configurazione dell'API Chat nella console Google Cloud. Per informazioni dettagliate su ciascun flag, consulta la documentazione di riferimento del comando update.
| Impostazione nella console Google Cloud | Bandiere |
|---|---|
| Nome dell'app | --display-name |
| URL avatar | --avatar-uri con l'URL HTTPS di un'immagine che soddisfa i requisiti dell'avatar o --clear-avatar-uri per utilizzare l'avatar predefinito |
| Descrizione | --description |
| Stato dell'app | --state=active o --state=disabled |
| Sintassi di markup | --markup-syntax=markdown o
--markup-syntax=chat |
| Partecipa a spazi e conversazioni di gruppo | --supports-multiuser-spaces o
--no-supports-multiuser-spaces |
| Impostazioni di connessione | Uno dei seguenti:
|
| Visibilità | --add-allowlisted-testing-principals,
--remove-allowlisted-testing-principals e
--clear-allowlisted-testing-principals |
| Errori di log in Logging | --error-logging-enabled o
--no-error-logging-enabled |
I comandi, le anteprime dei link e gli endpoint separati per ogni trigger non hanno flag. Per configurarle, utilizza un file di configurazione.
Ad esempio, per disattivare l'app di Chat senza modificare le altre impostazioni, esegui questo comando. Per riattivarla, utilizza --state=active.
gcloud beta workspace-add-ons chat-app-config update --state=disabledUtilizza un file di configurazione
Per conservare la configurazione in un file o per configurare impostazioni che non hanno flag, passa un file YAML o JSON al comando update. Il file utilizza i campi della risorsa chatAppConfig, che sono gli stessi campi stampati dal comando describe.
Crea un file contenente le impostazioni da aggiornare. Ad esempio, crea un file denominato
chat_app_config.yamlcon i seguenti contenuti:displayName: Cymbal Assistant description: Helps manage tasks and schedules avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png state: ACTIVE errorLoggingEnabled: true interactiveFeatureConfig: supportsMultiuserSpaces: true connectionConfig: httpEndpointConfig: commonUrl: https://example.com/chat appCommands: - commandId: 1 commandType: SLASH_COMMAND command: /help description: Show available commands urlPatterns: - hostPattern: example.com pathPrefix: tasks/ allowlistedTestingPrincipals: - USER_EMAILSostituisci
USER_EMAILcon l'indirizzo email di una persona o di un gruppo della tua organizzazione Google Workspace che può installare e testare l'app Chat.Esegui il comando
updatecon il flag--config-file:gcloud beta workspace-add-ons chat-app-config update \ --config-file=chat_app_config.yaml
Per iniziare dalla configurazione attuale di un'app di Chat, salva l'output del comando describe in un file:
gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yamlPoi modifica il file, elimina i campi che non vuoi modificare e passa il file al comando update. Se il file contiene un'impostazione che il comando non può aggiornare, il comando non va a buon fine. Per maggiori dettagli, consulta Limitazioni.
Il comando update ignora il campo name nel file. Aggiorna sempre il progetto Cloud impostato in gcloud CLI, in modo da poter utilizzare lo stesso file per configurare un'app di Chat in un altro progetto Cloud.
Come il comando applica le modifiche
- Vengono modificate solo le impostazioni specificate. Con i flag, il comando modifica le impostazioni dei flag che passi. Con un file di configurazione, modifica i campi presenti nel file, quindi il file non deve contenere l'intera configurazione. Le impostazioni di connessione sono un'eccezione: il tipo di connessione impostato sostituisce quello attuale e la versione di Dialogflow impostata sostituisce l'intera configurazione di Dialogflow.
- Gli elenchi vengono sostituiti nel loro insieme. Se il file contiene il campo
appCommands,urlPatternsoallowlistedTestingPrincipals, l'elenco nel file sostituisce l'elenco corrente. Per aggiungere o rimuovere singoli tester, utilizza invece i flag--add-allowlisted-testing-principalse--remove-allowlisted-testing-principals. - Un valore vuoto cancella un'impostazione. Ad esempio, un file che contiene
urlPatterns: []ininteractiveFeatureConfigrimuove tutti i pattern URL di anteprima dei link. - Un comando che non va a buon fine non apporta alcuna modifica. Se un valore non è valido, il comando stampa l'errore e lascia la configurazione invariata.
- Le richieste sono soggette a limitazione di frequenza. Il limite API limita il numero di richieste di lettura e di aggiornamento al minuto per ogni progetto cloud e per ogni organizzazione. Ogni comando
updateinvia una richiesta di aggiornamento. Se aggiungi o rimuovi tester con flag, il comando invia anche una richiesta di lettura. Per modificare più impostazioni, passale in un unico comando o file anziché eseguire un comando per ogni impostazione.
Limitazioni
- I comandi supportano solo le app di Chat create come componenti aggiuntivi di Google Workspace.
- I comandi non supportano i service account o la simulazione dell'identità dei service account. Devi accedere a gcloud CLI con un account utente.
- Un progetto cloud ha una configurazione dell'app di Chat e i comandi non possono eliminarla. Per impedire alle persone di utilizzare l'app di Chat, imposta il suo stato su disattivato o elimina il progetto Cloud.
- Un aggiornamento si applica all'app Chat live. I comandi non hanno una modalità bozza o dry run.
- Mentre un'app di Chat è pubblicata o in fase di revisione in Google Workspace Marketplace, i comandi non possono modificarne il nome visualizzato, l'avatar, la descrizione, i comandi o i pattern URL delle anteprime dei link.
- I comandi supportano le impostazioni nella risorsa
chatAppConfig. Per configurare un'impostazione non inclusa nella risorsa, utilizza la console Google Cloud.
Risoluzione dei problemi
Se un comando non va a buon fine, trova il testo del messaggio di errore nella tabella seguente. Se il messaggio inizia con uno stato come INVALID_ARGUMENT, l'API Google Workspace Add-ons ha rifiutato la richiesta e il testo dopo lo stato descrive il problema.
| Il messaggio di errore contiene | Causa | Soluzione |
|---|---|---|
Invalid choice: 'chat-app-config' o Invalid choice: 'workspace-add-ons' |
Il comando non include beta o la tua versione di gcloud CLI non include i comandi. |
Inizia il comando con gcloud beta workspace-add-ons chat-app-config. Se l'errore persiste, aggiorna gcloud CLI all'ultima versione. |
PROJECT ID |
Il progetto è impostato su un numero di progetto. | Imposta il progetto sull'ID progetto. |
Failed to parse value(s) in protobuf |
Il file di configurazione contiene un campo che non viene riconosciuto da gcloud CLI. Il messaggio di errore indica il nome del campo. | Confronta il nome del campo con l'output del comando describe. Se il campo è nuovo, aggiorna gcloud CLI all'ultima versione. |
does not have permission to access projects instance |
L'API ha rifiutato la richiesta. Il testo dopo questo messaggio indica il motivo. Ad esempio:
|
Controlla i requisiti nella sezione Prima di iniziare. |
INVALID_ARGUMENT |
Un valore non è valido. Ad esempio, il nome visualizzato deve contenere da 3 a 25 caratteri e la descrizione da 1 a 40 caratteri. Se il messaggio contiene not found or deleted, l'ID progetto non è corretto. |
Correggi il valore descritto nel messaggio di errore ed esegui di nuovo il comando. |
FAILED_PRECONDITION |
L'app di Chat non consente la richiesta. Ad esempio, non è stato creato come componente aggiuntivo di Google Workspace o è stato pubblicato in Google Workspace Marketplace e l'impostazione non può essere modificata. | Segui le istruzioni nel messaggio di errore. Per configurare un'app di Chat che non è un componente aggiuntivo di Google Workspace, utilizza la console Google Cloud o convertila. |
RESOURCE_EXHAUSTED o 429 |
L'API ha ricevuto troppe richieste per il progetto cloud o per la tua organizzazione in un breve periodo di tempo. | Attendi un minuto, quindi esegui di nuovo il comando. |
Configura l'app di Chat utilizzando l'API Google Workspace Add-ons
Anziché configurare manualmente l'app di Chat nella console Google Cloud, puoi leggere e aggiornare in modo programmatico la configurazione di un'app di Chat creata come componente aggiuntivo di Google Workspace utilizzando la risorsa chatAppConfig nell'Google Workspace add-ons API.
chatAppConfig è una risorsa singleton che esiste sempre per ogni progetto Cloud. Prima di salvare una configurazione per la prima volta, la risorsa contiene una configurazione vuota (che è anche ciò che GetChatAppConfig restituisce se leggi la risorsa prima del primo salvataggio). Poiché la risorsa esiste già, non è necessario crearla separatamente. Utilizza UpdateChatAppConfig sia per salvare la configurazione iniziale sia per aggiornare una configurazione esistente.
Prerequisiti e autenticazione
Prima di chiamare GetChatAppConfig o UpdateChatAppConfig, completa i seguenti prerequisiti:
- Abilita l'API dei componenti aggiuntivi di Google Workspace (
gsuiteaddons.googleapis.com) nel tuo progetto Cloud. Facoltativamente, puoi attivare l'API Google Chat (chat.googleapis.com) se vuoi visualizzare o aggiornare la configurazione dell'app Chat nella console Google Cloud o chiamare l'API Chat. - Esegui l'autenticazione come utente umano con una credenziale OAuth 2.0 che include l'ambito
https://www.googleapis.com/auth/cloud-platform. L'autenticazione del service account non è supportata per i metodichatAppConfig. - Assicurati che l'utente autenticato disponga delle autorizzazioni Identity and Access Management (IAM) richieste per il progetto Cloud di destinazione:
gsuiteaddons.chatAppConfigs.getechat.bots.getper leggere la configurazione (GetChatAppConfig).gsuiteaddons.chatAppConfigs.update,chat.bots.updateechat.bots.getper aggiornare la configurazione (UpdateChatAppConfig).
- Se utilizzi una libreria client, installa l'ultima versione della libreria client dell'API dei componenti aggiuntivi di Google Workspace per il tuo linguaggio. Per un elenco delle librerie client, consulta il Riferimento API dei componenti aggiuntivi di Google Workspace.
Aggiorna la configurazione di un'app di Chat
Per configurare un'app di Chat per la prima volta o aggiornare una configurazione esistente, invia una richiesta PATCH (UpdateChatAppConfig) alla risorsa singleton chatAppConfig per il tuo progetto cloud:
- Per il salvataggio iniziale di un progetto cloud con un
chatAppConfigvuoto, sono obbligatoridisplayName(da 3 a 25 caratteri) edescription(da 1 a 40 caratteri). Se omettiinteractiveFeatureConfigal momento del salvataggio iniziale, l'app Chat viene configurata come non interattiva. - Per gli aggiornamenti successivi, utilizza il parametro di query facoltativo
updateMaskper specificare i campi separati da virgole da aggiornare (oppure omettiupdateMaskper aggiornare tutti i campi forniti). L'aggiornamento di un campo ripetuto (appCommands,urlPatternsoallowlistedTestingPrincipals) sostituisce l'intero elenco.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"name": "projects/PROJECT_NUMBER/chatAppConfig",
"displayName": "Cymbal Assistant",
"description": "Helps manage tasks and schedules",
"avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
"state": "ACTIVE",
"errorLoggingEnabled": true,
"markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
"interactiveFeatureConfig": {
"supportsMultiuserSpaces": false,
"connectionConfig": {
"httpEndpointConfig": {
"commonUrl": "https://example.com/chat"
}
},
"appCommands": [
{
"commandType": "SLASH_COMMAND",
"commandId": 1,
"command": "/help",
"description": "Show available commands",
"dialogEnabled": false
}
],
"urlPatterns": [
{
"hostPattern": "example.com",
"pathPrefix": "tasks/"
}
],
"allowlistedTestingPrincipals": [
"USER_EMAIL"
]
}
}
Sostituisci quanto segue nell'URL, nell'intestazione e nel corpo della richiesta:
PROJECT_NUMBER: il numero di progetto numerico del progetto cloud che ospita la tua app di Chat.ACCESS_TOKEN: un token di accesso OAuth 2.0 dell'utente autorizzato con l'ambitohttps://www.googleapis.com/auth/cloud-platform.USER_EMAIL: un indirizzo email o un gruppo Google della tua organizzazione Google Workspace da inserire nella lista consentita per testare l'app di Chat (ad esempio, il tuo indirizzo email).- I campi di configurazione di esempio nel corpo della richiesta (come
displayName,description,avatarUrieinteractiveFeatureConfig, inclusi la configurazione dell'endpoint, i comandi, i pattern URL di anteprima dei link e le entità di test) con i valori per la tua app Chat. Per informazioni dettagliate su tutti i campi e le opzioni degli endpoint supportati, consulta il riferimento RESTprojects.chatAppConfigeprojects.chatAppConfig.patch.
Ottieni la configurazione di un'app di Chat
Per leggere la configurazione attuale dell'app di Chat per un progetto Cloud, chiama GetChatAppConfig.
Puoi passare il parametro di query facoltativo view (ChatAppConfigView):
BASIC(predefinito): restituisce i metadati di base senzainteractiveFeatureConfig.FULL: restituisce tutti i campi di configurazione, inclusointeractiveFeatureConfig.
Se la configurazione dell'app di Chat non è ancora stata salvata per il progetto Cloud, il metodo restituisce un oggetto ChatAppConfig vuoto.
HTTP
GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN
Node.js
const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;
const client = new GSuiteAddOnsClient();
async function getChatAppConfig() {
const [response] = await client.getChatAppConfig({
name: 'projects/PROJECT_NUMBER/chatAppConfig',
view: 'FULL',
});
console.log(JSON.stringify(response, null, 2));
}
getChatAppConfig();
Python
from google.cloud import gsuiteaddons_v1
client = gsuiteaddons_v1.GSuiteAddOnsClient()
request = gsuiteaddons_v1.GetChatAppConfigRequest(
name="projects/PROJECT_NUMBER/chatAppConfig",
view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)
Limiti di utilizzo
I metodi chatAppConfig hanno quote per progetto. Se superi una quota, la richiesta non va a buon fine e restituisce un codice di stato HTTP 429: Too many requests. Per i limiti di quota, consulta Limiti di utilizzo dell'API Google Workspace Add-ons.
Risolvi i problemi
Se una richiesta chatAppConfig non va a buon fine, controlla il codice di stato HTTP e il campo message nella risposta di errore. La tabella seguente elenca gli errori comuni, le relative cause e come risolverli.
| Codice di stato HTTP | Cause comuni | Risoluzione |
|---|---|---|
400: Bad Request (INVALID_ARGUMENT) |
|
Controlla il campo message per individuare il campo non valido e correggi la richiesta. Per i campi e i valori supportati, consulta il
riferimento
projects.chatAppConfig. |
400: Bad Request (FAILED_PRECONDITION) |
|
|
403: Forbidden (PERMISSION_DENIED) |
|
|
404: Not Found (NOT_FOUND) |
Il progetto cloud nel nome della risorsa non esiste o l'utente autenticato non può accedervi. | Verifica che il nome della risorsa utilizzi il numero di progetto corretto nel formato projects/PROJECT_NUMBER/chatAppConfig e che l'utente abbia accesso al progetto cloud. |
429: Too Many Requests (RESOURCE_EXHAUSTED) |
La quota per progetto è stata superata. | Attendi e riprova a inviare la richiesta più tardi. Per i limiti, consulta Limiti di utilizzo. |
Considerazioni per i componenti aggiuntivi di Google Workspace esistenti
Le app di Chat richiedono una configurazione diversa rispetto ai componenti aggiuntivi di Google Workspace che estendono altre applicazioni Google Workspace. Se il tuo componente aggiuntivo estende altre applicazioni Google Workspace, tieni presente i seguenti requisiti per la configurazione dell'app di Chat:
- Sia i privati che gli amministratori di Google Workspace devono essere in grado di installare il tuo componente aggiuntivo dal Marketplace. Puoi configurare queste impostazioni di installazione nell'SDK Marketplace.
- Le app di Chat non utilizzano il nome e il logo che configuri per altre applicazioni Google Workspace nell'oggetto
addons.commondel manifest. - Per i componenti aggiuntivi pubblicati su Google Workspace Marketplace, non puoi salvare una bozza delle modifiche alle impostazioni di configurazione dell'API Google Chat. Dopo aver aggiornato e salvato le impostazioni di configurazione dell'API Chat, l'app Chat aggiornata è immediatamente disponibile per tutti gli utenti esistenti. Per aggiornare la tua scheda del Marketplace, puoi creare una bozza prima di inviare eventuali modifiche.
- Se hai creato il componente aggiuntivo utilizzando Apps Script:
- Devi utilizzare lo stesso ID deployment di Apps Script che utilizzi per il resto della configurazione del componente aggiuntivo.
- Non puoi utilizzare l'editor di Apps Script per installare deployment di test in Chat. Devi invece installarle direttamente dalla UI di Chat.
- Se hai creato il componente aggiuntivo utilizzando un servizio HTTP, ometti i dettagli di configurazione dell'app di Chat nel manifest
projects.deploymentsche crei utilizzando l'API Google Workspace Add-ons. I deployment HTTP specificati nell'SDK di Google Workspace Marketplace vengono utilizzati solo per altre applicazioni Google Workspace. Invece, configura la tua app Chat nella console Google Cloud, con gcloud CLI o utilizzando la risorsachatAppConfignell'API Google Workspace Add-ons.
Concedi ad altre persone l'autorizzazione per configurare l'API Chat
Puoi concedere l'accesso a utenti specifici alla pagina di configurazione dell'app Chat assegnando loro il ruolo Google Cloud Identity Access Management (IAM) Chat apps Owner o Chat apps Viewer. Gli utenti con questi ruoli non possono accedere alla pagina di configurazione delle app di Chat utilizzando la dashboard API e servizi, ma possono accedere alla pagina di configurazione andando alla console Google Cloud per il progetto cloud host dell'app di Chat come segue:
https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID
Dove PROJECT_ID è l'ID progetto Google Cloud che ospita l'app Chat.
Argomenti correlati
- Scegli un'architettura per l'app di Chat
- Ricevere e rispondere alle interazioni degli utenti
- Testa le funzionalità interattive per le app Google Chat
App di Chat che non sono componenti aggiuntivi: configura l'API Google Chat
Se gestisci un'app di Chat che non è un componente aggiuntivo di Google Workspace, la tua configurazione utilizza un singolo endpoint per tutti gli eventi di interazione anziché trigger per evento:
Nella console Google Cloud, vai alla pagina Configurazione dell'API Chat:
In Funzionalità interattive, attiva Abilita funzionalità interattive.
Deseleziona Crea questa app di Chat come componente aggiuntivo di Google Workspace. Si apre una finestra di dialogo in cui ti viene chiesto di confermare. Nella finestra di dialogo, fai clic su Disattiva.
In Funzionalità, seleziona Supporta la home page dell'app o Partecipa a spazi e conversazioni di gruppo, a seconda delle esigenze.
In Impostazioni di connessione, specifica un singolo endpoint per la tua app di Chat (URL endpoint HTTP, ID deployment Apps Script, Nome argomento Cloud Pub/Sub o Dialogflow).
Configura le opzioni facoltative Comandi, Prompt iniziali, Anteprime dei link, Visibilità e Log, quindi fai clic su Salva.
Per eseguire l'upgrade di un'app di Chat che non è un componente aggiuntivo a un componente aggiuntivo di Google Workspace che estende Google Chat, consulta Converti un'app di Google Chat in un componente aggiuntivo di Google Workspace.