Configurare l'API Google Chat

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

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:

L'app Google Chat crea uno spazio per un utente.
Figura 1. Il messaggio di attribuzione che Chat visualizza quando viene utilizzato il metodo 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:

  1. Nella console Google Cloud, vai alla pagina API Chat e fai clic sulla pagina Configurazione:

    Vai alla pagina di configurazione dell'API Chat

  2. In Informazioni sull'applicazione, compila i campi Nome app, URL avatar e Descrizione.

  3. (Facoltativo) Compila il campo Descrizione lunga.

  4. (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.

  5. 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:

    1. 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.
    2. 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.
    3. (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.
    4. (Facoltativo) Aggiungi altre funzionalità interattive, come sessioni, prompt iniziali, comandi (comandi rapidi, comandi slash e azioni sui messaggi) o anteprime dei link.

    5. 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.
  6. (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.

  7. 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

  1. Installa la gcloud CLI. Se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.
  2. Accedi a gcloud CLI con il tuo account utente. I comandi non supportano i service account.

    gcloud auth login
  3. Imposta 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_ID

    In alternativa, aggiungi il flag --project a ogni comando.

  4. Abilita l'API dei componenti aggiuntivi di Google Workspace nel progetto Cloud:

    gcloud services enable gsuiteaddons.googleapis.com
  5. Assicurati 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'autorizzazione serviceusage.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.

Visualizza la configurazione

Per visualizzare la configurazione dell'app di Chat, esegui il comando describe:

gcloud beta workspace-add-ons chat-app-config describe

L'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-enabled

Sostituisci 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:
  • URL endpoint HTTP: --http-endpoint-url
  • Apps Script: --apps-script-deployment-id
  • Cloud Pub/Sub: --pubsub-topic con un argomento nello stesso progetto Cloud, nel formato projects/PROJECT_ID/topics/TOPIC_ID
  • Dialogflow: --dialogflow-edition=es o --dialogflow-edition=cx con --dialogflow-agent impostato sul nome della risorsa dell'agente o dell'ambiente, ad esempio projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID
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=disabled

Utilizza 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.

  1. Crea un file contenente le impostazioni da aggiornare. Ad esempio, crea un file denominato chat_app_config.yaml con 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_EMAIL
    

    Sostituisci USER_EMAIL con l'indirizzo email di una persona o di un gruppo della tua organizzazione Google Workspace che può installare e testare l'app Chat.

  2. Esegui il comando update con 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.yaml

Poi 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, urlPatterns o allowlistedTestingPrincipals, l'elenco nel file sostituisce l'elenco corrente. Per aggiungere o rimuovere singoli tester, utilizza invece i flag --add-allowlisted-testing-principals e --remove-allowlisted-testing-principals.
  • Un valore vuoto cancella un'impostazione. Ad esempio, un file che contiene urlPatterns: [] in interactiveFeatureConfig rimuove 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 update invia 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:
  • Il tuo account non dispone dei ruoli IAM richiesti. Se il testo contiene Caller does not have required permission to use project, il ruolo Service Usage Consumer non è presente.
  • L'API dei componenti aggiuntivi di Google Workspace non è abilitata nel progetto Cloud.
  • Hai eseguito l'accesso con un service account.
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:

  1. 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.
  2. 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 metodi chatAppConfig.
  3. Assicurati che l'utente autenticato disponga delle autorizzazioni Identity and Access Management (IAM) richieste per il progetto Cloud di destinazione:
    • gsuiteaddons.chatAppConfigs.get e chat.bots.get per leggere la configurazione (GetChatAppConfig).
    • gsuiteaddons.chatAppConfigs.update, chat.bots.update e chat.bots.get per aggiornare la configurazione (UpdateChatAppConfig).
  4. 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 chatAppConfig vuoto, sono obbligatori displayName (da 3 a 25 caratteri) e description (da 1 a 40 caratteri). Se ometti interactiveFeatureConfig al momento del salvataggio iniziale, l'app Chat viene configurata come non interattiva.
  • Per gli aggiornamenti successivi, utilizza il parametro di query facoltativo updateMask per specificare i campi separati da virgole da aggiornare (oppure ometti updateMask per aggiornare tutti i campi forniti). L'aggiornamento di un campo ripetuto (appCommands, urlPatterns o allowlistedTestingPrincipals) 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'ambito https://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, avatarUri e interactiveFeatureConfig, 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 REST projects.chatAppConfig e projects.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 senza interactiveFeatureConfig.
  • FULL: restituisce tutti i campi di configurazione, incluso interactiveFeatureConfig.

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)
  • updateMask contiene un campo che non esiste o non può essere aggiornato.
  • Un valore del campo è mancante o non valido. Ad esempio, interactiveFeatureConfig non include un connectionConfig.
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)
  • L'app di Chat non è creata come componente aggiuntivo di Google Workspace.
  • Il campo non può essere modificato perché l'app di Chat è pubblicata su Google Workspace Marketplace.
  • Il nuovo valore non è compatibile con la configurazione dell'app di Chat esistente.
  • Converti l'app di Chat in un componente aggiuntivo di Google Workspace o configurala nella console Google Cloud.
  • Segui le istruzioni nel campo message per aggiornare la scheda pubblicata.
  • Controlla il campo message per l'impostazione in conflitto e aggiorna entrambe le impostazioni nella stessa richiesta o modifica prima l'impostazione esistente.
403: Forbidden (PERMISSION_DENIED)
  • L'utente autenticato non dispone delle autorizzazioni IAM richieste per il progetto Cloud.
  • La richiesta viene autenticata con un service account anziché con un account utente.
  • Concedi all'utente le autorizzazioni elencate in Prerequisiti e autenticazione.
  • Autenticati come utente umano con l'ambito https://www.googleapis.com/auth/cloud-platform.
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.common del 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:
  • Se hai creato il componente aggiuntivo utilizzando un servizio HTTP, ometti i dettagli di configurazione dell'app di Chat nel manifest projects.deployments che 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 risorsa chatAppConfig nell'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.

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:

  1. Nella console Google Cloud, vai alla pagina Configurazione dell'API Chat:

    Vai alla pagina di configurazione dell'API Chat

  2. In Funzionalità interattive, attiva Abilita funzionalità interattive.

  3. 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.

  4. In Funzionalità, seleziona Supporta la home page dell'app o Partecipa a spazi e conversazioni di gruppo, a seconda delle esigenze.

  5. 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).

  6. 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.