Creare uno spazio di Google Chat e aggiungere membri

Questa guida spiega come utilizzare il metodo setUp() nella risorsa Space dell'API Google Chat per creare uno spazio di Chat e aggiungervi membri.

La risorsa Space rappresenta un luogo in cui persone e app di chat possono inviare messaggi, condividere file e collaborare. Esistono diversi tipi di spazi:

  • I messaggi diretti sono conversazioni tra due utenti o tra un utente e un'app di chat.
  • Le chat di gruppo sono conversazioni tra tre o più utenti e app di chat.
  • Gli spazi con nome sono luoghi permanenti in cui le persone inviano messaggi, condividono file e collaborano.

Puoi utilizzare il metodo setUp() per eseguire una delle seguenti operazioni:

  • Crea uno spazio con nome con i membri iniziali.
  • Crea un messaggio diretto tra due persone.
  • Configurare un messaggio di gruppo tra più persone.

Quando configuri uno spazio, considera quanto segue:

  • L'utente chiamante (autenticato) viene aggiunto automaticamente allo spazio, quindi non è necessario specificare la sua appartenenza alla richiesta.
  • Quando crei un messaggio diretto, se esiste un messaggio diretto tra due utenti, viene restituito. In caso contrario, viene creato un messaggio diretto.
  • Quando crei una chat di gruppo, se nessuna delle iscrizioni fornite nella richiesta viene aggiunta correttamente alla chat di gruppo (ad esempio, problema di autorizzazione), potrebbe essere creata una chat di gruppo vuota (incluso solo l'utente che chiama).
  • Non puoi configurare spazi con risposte in thread o aggiungere persone esterne alla tua organizzazione Google Workspace.
  • Le iscrizioni duplicate (incluso l'utente chiamante) fornite nella richiesta vengono filtrate anziché generare un errore della richiesta.
  • Quando un amministratore di Google Workspace installa un'app di Chat per l'intera organizzazione Google Workspace, Google Chat crea un messaggio diretto tra l'app di Chat installata e ogni utente dell'organizzazione, quindi non è necessario configurare i messaggi diretti a livello di programmazione. In alternativa, elenca gli spazi per restituire tutti i messaggi diretti o trova un messaggio diretto per visualizzare i dettagli di un messaggio diretto specifico.

Prerequisiti

Node.js

Python

Java

Apps Script

Configurare uno spazio

Per configurare uno spazio, passa quanto segue nella richiesta:

  • Specifica l'ambito di autorizzazione chat.spaces.create o chat.spaces.
  • Chiama il metodo SetUpSpace().
  • Passa space come istanza di Space con tutti i campi necessari, ad esempio displayName o spaceType.
  • Passa memberships come array di istanze Membership. Per ogni istanza:
    • Specifica users/{user} per aggiungere un utente umano come membro dello spazio, dove {user} è l'{person_id} per person dell'API People o l'ID di un user nell'API Directory. Ad esempio, se la persona dell'API People resourceName è people/123456789, puoi aggiungere l'utente allo spazio includendo un'iscrizione con users/123456789 come member.name.
    • Specifica groups/{group} per aggiungere un gruppo come membro dello spazio, dove {group} è l'ID gruppo per cui vuoi creare l'iscrizione. L'ID del gruppo può essere recuperato utilizzando l'API Cloud Identity. Ad esempio, se l'API Cloud Identity restituisce un gruppo con il nome groups/123456789, imposta membership.groupMember.name su groups/123456789. I gruppi Google non possono essere aggiunti a una chat di gruppo o a un messaggio diretto, ma solo a uno spazio denominato.

Per creare un messaggio diretto tra l'utente chiamante e un altro utente umano, specifica l'appartenenza dell'utente umano nella richiesta.

Per creare un messaggio diretto tra l'utente chiamante e l'app chiamante, imposta space.singleUserBotDm su true e non specificare abbonamenti. Puoi utilizzare questo metodo solo per configurare un messaggio diretto con l'app di chiamata. Per aggiungere l'app di chiamata come membro di uno spazio o di un messaggio diretto esistente tra due utenti umani, consulta Creare un'iscrizione.

L'esempio seguente crea uno spazio denominato e un abbonamento allo spazio per due utenti umani (l'utente autenticato e un altro utente).

Node.js

chat/client-libraries/cloud/set-up-space-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.spaces.create',
];

// This sample shows how to set up a named space with one initial member
// with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    space: {
      spaceType: 'SPACE',
      // Replace DISPLAY_NAME here.
      displayName: 'DISPLAY_NAME',
    },
    memberships: [
      {
        member: {
          // Replace USER_NAME here.
          name: 'users/USER_NAME',
          type: 'HUMAN',
        },
      },
    ],
  };

  // Make the request
  const response = await chatClient.setUpSpace(request);

  // Handle the response
  console.log(response);
}

await main();

Python

chat/client-libraries/cloud/set_up_space_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

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

def set_up_space_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.SetUpSpaceRequest(
        space = {
            "space_type": 'SPACE',
            # Replace DISPLAY_NAME here.
            "display_name": 'DISPLAY_NAME'
        },
        memberships = [{
            "member": {
                # Replace USER_NAME here.
                "name": 'users/USER_NAME',
                "type_": 'HUMAN'
            }
        }]
    )

    # Make the request
    response = client.set_up_space(request)

    # Handle the response
    print(response)

set_up_space_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/SetUpSpaceUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SetUpSpaceRequest;
import com.google.chat.v1.Space;
import com.google.chat.v1.User;

// This sample shows how to set up a named space with one initial member with
// user credential.
public class SetUpSpaceUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.spaces.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      SetUpSpaceRequest.Builder request = SetUpSpaceRequest.newBuilder()
        .setSpace(Space.newBuilder()
          .setSpaceType(Space.SpaceType.SPACE)
          // Replace DISPLAY_NAME here.
          .setDisplayName("DISPLAY_NAME"))
        .addAllMemberships(ImmutableList.of(Membership.newBuilder()
          .setMember(User.newBuilder()
            // Replace USER_NAME here.
            .setName("users/USER_NAME")
            .setType(User.Type.HUMAN)).build()));
      Space response = chatServiceClient.setUpSpace(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to set up a named space with one initial member with
 * user credential.
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.spaces.create'
 * referenced in the manifest file (appsscript.json).
 */
function setUpSpaceUserCred() {
  // Initialize request argument(s)
  const space = {
    spaceType: "SPACE",
    // TODO(developer): Replace DISPLAY_NAME here
    displayName: "DISPLAY_NAME",
  };
  const memberships = [
    {
      member: {
        // TODO(developer): Replace USER_NAME here
        name: "users/USER_NAME",
        // User type for the membership
        type: "HUMAN",
      },
    },
  ];

  // Make the request
  const response = Chat.Spaces.setup({
    space: space,
    memberships: memberships,
  });

  // Handle the response
  console.log(response);
}

Per eseguire l'esempio, sostituisci quanto segue:

  • DISPLAY_NAME: il nome visualizzato del nuovo spazio.
  • USER_NAME: l'ID dell'altro utente per cui includere un abbonamento.

Per andare allo spazio, utilizza l'ID risorsa dello spazio per creare il relativo URL. Puoi ottenere l'ID risorsa dallo spazio name nel corpo della risposta di Google Chat. Ad esempio, se l'name del tuo spazio è spaces/1234567, puoi accedere allo spazio utilizzando il seguente URL: https://mail.google.com/chat/u/0/#chat/space/1234567.