Servizio chat avanzato

Gestisci spazi, membri e messaggi di Chat.

Il servizio Chat avanzato ti consente di utilizzare l' API Google Chat in Google Apps Script. Questa API consente agli script di trovare, creare e modificare gli spazi di Chat, aggiungere o rimuovere membri dagli spazi e leggere o pubblicare messaggi con testo, schede, allegati e reazioni.

Prerequisiti

Si tratta di un servizio avanzato che devi attivare prima dell'uso.

Riferimento

Per saperne di più su questo servizio, consulta la documentazione di riferimento dell'API Chat. Come tutti i servizi avanzati in Apps Script, il servizio Chat utilizza gli stessi oggetti, metodi e parametri dell'API pubblica.

Codice campione

Questi esempi mostrano come eseguire le azioni comuni dell'API Google Chat utilizzando il servizio avanzato.

Pubblicare un messaggio con le credenziali utente

L'esempio seguente mostra come pubblicare un messaggio in uno spazio di Chat per conto dell'utente.

  1. Aggiungi l'ambito di autorizzazione chat.messages.create al file appsscript.json del progetto Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

  2. Aggiungi una funzione come questa al codice del progetto Apps Script:

    advanced/chat.gs
    /**
 * Posts a new message to the specified space on behalf of the user.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithUserCredentials(spaceName) {
  try {
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(message, spaceName);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

Pubblicare un messaggio con le credenziali dell'app

L'esempio seguente mostra come pubblicare un messaggio in uno spazio di Chat per conto dell'app. L'utilizzo del servizio Chat avanzato con un account di servizio non richiede la specifica degli ambiti di autorizzazione in appsscript.json. Per maggiori dettagli sull' autenticazione con gli account di servizio, vedi Eseguire l'autenticazione come app Google Chat.

advanced/chat.gs
/**
 * Posts a new message to the specified space on behalf of the app.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithAppCredentials(spaceName) {
  try {
    // See https://developers.google.com/chat/api/guides/auth/service-accounts
    // for details on how to obtain a service account OAuth token.
    const appToken = getToken_();
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(
      message,
      spaceName,
      {},
      // Authenticate with the service account token.
      { Authorization: `Bearer ${appToken}` },
    );
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

Recuperare uno spazio

L'esempio seguente mostra come recuperare informazioni su uno spazio di Chat.

  1. Aggiungi l'ambito di autorizzazione chat.spaces.readonly al file appsscript.json del progetto Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.readonly"
]

  2. Aggiungi una funzione come questa al codice del progetto Apps Script:

    advanced/chat.gs
    /**
 * Gets information about a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function getSpace(spaceName) {
  try {
    const space = Chat.Spaces.get(spaceName);
    console.log("Space display name: %s", space.displayName);
    console.log("Space type: %s", space.spaceType);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to get space with error %s", err.message);
  }
}

Creare uno spazio

L'esempio seguente mostra come creare uno spazio di Chat.

  1. Aggiungi l'ambito di autorizzazione chat.spaces.create al file appsscript.json del progetto Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.create"
]

  2. Aggiungi una funzione come questa al codice del progetto Apps Script:

    advanced/chat.gs
    /**
 * Creates a new Chat space.
 */
function createSpace() {
  try {
    const space = { displayName: "New Space", spaceType: "SPACE" };
    Chat.Spaces.create(space);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create space with error %s", err.message);
  }
}

Elencare le appartenenze

L'esempio seguente mostra come elencare tutti i membri di uno spazio di Chat.

  1. Aggiungi l'ambito di autorizzazione chat.memberships.readonly al file appsscript.json del progetto Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.memberships.readonly"
]

  2. Aggiungi una funzione come questa al codice del progetto Apps Script:

    advanced/chat.gs
    /**
 * Lists all the members of a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function listMemberships(spaceName) {
  let response;
  let pageToken = null;
  try {
    do {
      response = Chat.Spaces.Members.list(spaceName, {
        pageSize: 10,
        pageToken: pageToken,
      });
      if (!response.memberships || response.memberships.length === 0) {
        pageToken = response.nextPageToken;
        continue;
      }
      for (const membership of response.memberships) {
        console.log(
          "Member: %s, Role: %s",
          membership.member.displayName,
          membership.role,
        );
      }
      pageToken = response.nextPageToken;
    } while (pageToken);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
}

Risoluzione dei problemi

Se viene visualizzato Error 400: invalid_scope con il messaggio di errore Some requested scopes cannot be shown, significa che non hai specificato ambiti di autorizzazione nel file appsscript.json del progetto Apps Script. Nella maggior parte dei casi, Apps Script determina automaticamente gli ambiti di cui ha bisogno uno script, ma quando utilizzi il servizio Chat avanzato, devi aggiungere manualmente gli ambiti di autorizzazione utilizzati dallo script al file manifest del progetto Apps Script. Vedi Impostare ambiti espliciti.

Per risolvere l'errore, aggiungi gli ambiti di autorizzazione appropriati al file appsscript.json del progetto Apps Script come parte dell'array oauthScopes. Ad esempio, per chiamare il spaces.messages.create metodo, aggiungi quanto segue:

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

Limiti e considerazioni

Il servizio Chat avanzato non supporta:

Per scaricare un allegato di un messaggio o chiamare un metodo di anteprima per gli sviluppatori, usa UrlFetchApp invece.