Inviter ou ajouter un utilisateur, un groupe Google ou une application Google Chat à un espace

Ce guide explique comment utiliser la méthode create() sur la ressource Membership de l'API Google Chat pour inviter ou ajouter un utilisateur, un groupe Google ou une application Chat à un espace (également appelé "créer un accès"). Lorsque vous créez un accès, si la règle d'acceptation automatique du membre spécifié est désactivée, il est invité et doit accepter l'invitation à l'espace avant de le rejoindre. Sinon, la création d'une adhésion ajoute le membre directement à l'espace spécifié.

Si vous êtes administrateur Google Workspace, vous pouvez ajouter des utilisateurs, des groupes Google ou des applications Chat à n'importe quel espace de votre organisation Google Workspace.

La ressource Membership indique si un utilisateur humain ou une application Google Chat est invité à un espace, en fait partie ou en est absent.

Prérequis

Node.js

Python

Java

Apps Script

Inviter ou ajouter un utilisateur à un espace en tant qu'utilisateur

Pour inviter ou ajouter un utilisateur à un espace avec authentification utilisateur, transmettez les éléments suivants dans votre requête:

  • Spécifiez le champ d'application de l'autorisation chat.memberships.
  • Appelez la méthode CreateMembership().
  • Transmettez parent comme nom de ressource de l'espace dans lequel créer l'appartenance.
  • Transmettez membership en tant qu'instance de Membership, avec son champ member défini comme suit :
    • Le champ type défini sur HUMAN.
    • Le champ name défini sur users/{user}, où {user} est la personne que vous souhaitez ajouter à l'espace. Pour spécifier l'utilisateur Chat, remplacez {user} par l'une des valeurs suivantes :
      • ID de la personne dans l'API People. Par exemple, si l'API People person resourceName est people/123456789, utilisez la valeur users/123456789.
      • ID de l'utilisateur dans l'API Directory.
      • Adresse e-mail de l'utilisateur. Par exemple, users/222larabrown@gmail.com ou users/larabrown@cymbalgroup.com. Si l'utilisateur utilise un compte Google ou appartient à une autre organisation Google Workspace, vous devez utiliser son adresse e-mail.

L'exemple suivant ajoute un utilisateur à un espace avec authentification des utilisateurs:

Node.js

chat/client-libraries/cloud/create-membership-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a human user
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Replace USER_NAME here
        name: 'users/USER_NAME',
        // User type for the membership
        type: 'HUMAN'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_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.memberships"]

# This sample shows how to create membership with user credential for a human
# user
def create_membership_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # Replace USER_NAME here
                "name": "users/USER_NAME",
                # user type for the membership
                "type_": "HUMAN"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for a human
// user.
public class CreateMembershipUserCred {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // replace USER_NAME here
            .setName("users/USER_NAME")
            // user type for the membership
            .setType(User.Type.HUMAN)));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a human user
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    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.Members.create(membership, parent);

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

Pour exécuter l'exemple, remplacez les éléments suivants:

  • SPACE_NAME: ID de l'name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() ou à partir de l'URL de l'espace.
  • USER_NAME: ID utilisateur.

L'API Chat renvoie une instance de Membership qui détaille l'appartenance de l'utilisateur créée.

Inviter ou ajouter un groupe Google à un espace

Pour inviter ou ajouter un groupe Google à un espace avec authentification utilisateur (l'authentification de l'application n'est pas compatible avec l'invitation ou l'ajout d'un groupe Google à un espace), transmettez les éléments suivants dans votre requête:

  • Spécifiez le champ d'application de l'autorisation chat.memberships.
  • Appelez la méthode CreateMembership().
  • Transmettez parent comme nom de ressource de l'espace dans lequel créer l'appartenance.
  • Transmettez membership en tant qu'instance de Membership, où le champ name de groupMember est défini sur groups/{group}, où {group} est l'ID de groupe pour lequel vous souhaitez créer une appartenance. L'ID du groupe peut être récupéré à l'aide de l'API Cloud Identity.

Vous ne pouvez pas ajouter de groupes Google à une discussion de groupe ni à un message privé, mais uniquement à un espace nommé.

L'exemple suivant ajoute un groupe à un espace nommé avec authentification des utilisateurs:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-group.js
import {createClientWithUserCredentials} from './authentication-utils.js';

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

// This sample shows how to create membership with user credential for a group
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      groupMember: {
        // Replace GROUP_NAME here
        name: 'groups/GROUP_NAME'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_group.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.memberships"]

# This sample shows how to create membership with user credential for a group
def create_membership_with_user_cred_for_group():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "groupMember": {
                # Replace GROUP_NAME here
                "name": "groups/GROUP_NAME"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_group()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForGroup.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.Group;

// This sample shows how to create membership with user credential for a group.
public class CreateMembershipUserCredForGroup {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setGroupMember(Group.newBuilder()
            // replace GROUP_NAME here
            .setName("groups/GROUP_NAME")));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with user credential for a group
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForGroup() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    groupMember: {
      // TODO(developer): Replace GROUP_NAME here
      name: 'groups/GROUP_NAME'
    }
  };

  // Make the request
  const response = Chat.Spaces.Members.create(membership, parent);

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

Pour exécuter l'exemple, remplacez les éléments suivants:

  • SPACE_NAME: ID de l'name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() ou à partir de l'URL de l'espace.
  • GROUP_NAME: ID de groupe.

L'API Chat renvoie une instance de Membership qui détaille l'appartenance de l'utilisateur créée.

Ajouter une application Chat à un espace

Une application Chat ne peut pas ajouter une autre application en tant que membre d'un espace. Pour ajouter une application Chat à un espace ou à un message privé entre deux utilisateurs, transmettez les éléments suivants dans votre requête avec l'authentification de l'utilisateur (l'authentification de l'application n'est pas compatible avec l'invitation ni l'ajout d'une application Chat à un espace):

  • Spécifiez le champ d'application de l'autorisation chat.memberships.app.
  • Appelez la méthode CreateMembership().
  • Transmettez parent comme nom de ressource de l'espace dans lequel créer l'appartenance.
  • Transmettez membership en tant qu'instance de Membership, avec son champ member défini comme suit :
    • Le champ type défini sur BOT.
    • Le champ name défini sur users/app, un alias représentant l'application qui appelle l'API Chat.

L'exemple suivant ajoute une application Chat à un espace:

Node.js

chat/client-libraries/cloud/create-membership-user-cred-for-app.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.memberships.app'];

// This sample shows how to create membership with app credential for an app
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    membership: {
      member: {
        // Member name for app membership, do not change this
        name: 'users/app',
        // User type for the membership
        type: 'BOT'
      }
    }
  };

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

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

main().catch(console.error);

Python

chat/client-libraries/cloud/create_membership_user_cred_for_app.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.memberships.app"]

# This sample shows how to create membership with app credential for an app
def create_membership_with_user_cred_for_app():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMembershipRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        membership = {
            "member": {
                # member name for app membership, do not change this.
                "name": "users/app",
                # user type for the membership
                "type_": "BOT"
            }
        }
    )

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

    # Handle the response
    print(response)

create_membership_with_user_cred_for_app()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMembershipUserCredForApp.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMembershipRequest;
import com.google.chat.v1.Membership;
import com.google.chat.v1.SpaceName;
import com.google.chat.v1.User;

// This sample shows how to create membership with user credential for the
// calling app.
public class CreateMembershipUserCredForApp {

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

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMembershipRequest.Builder request = CreateMembershipRequest.newBuilder()
        // replace SPACE_NAME here
        .setParent("spaces/SPACE_NAME")
        .setMembership(Membership.newBuilder()
          .setMember(User.newBuilder()
            // member name for app membership, do not change this.
            .setName("users/app")
            // user type for the membership
            .setType(User.Type.BOT)));
      Membership response = chatServiceClient.createMembership(request.build());

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

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create membership with app credential for an app
 * 
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.memberships.app'
 * referenced in the manifest file (appsscript.json).
 */
function createMembershipUserCredForApp() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';
  const membership = {
    member: {
      // Member name for app membership, do not change this
      name: 'users/app',
      // User type for the membership
      type: 'BOT'
    }
  };

  // Make the request
  const response = Chat.Spaces.Members.create(membership, parent);

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

Pour exécuter l'exemple, remplacez SPACE_NAME par l'ID de l'name de l'espace. Vous pouvez obtenir l'ID en appelant la méthode ListSpaces() ou à partir de l'URL de l'espace.

L'API Chat renvoie une instance de Membership qui détaille l'appartenance de l'utilisateur créée.

Inviter ou ajouter un utilisateur à un espace en tant qu'application Chat

L'authentification de l'application nécessite une approbation de l'administrateur unique.

Pour inviter ou ajouter un utilisateur à un espace avec authentification de l'application, transmettez les éléments suivants dans votre requête:

  • Spécifiez le champ d'application de l'autorisation chat.app.memberships.
  • Appelez la méthode create sur la ressource membership.
  • Définissez parent sur le nom de la ressource de l'espace dans lequel créer l'appartenance.
  • Définissez member sur users/{user}, où {user} est la personne pour laquelle vous souhaitez créer un abonnement et est l'une des valeurs suivantes :
    • ID de la personne dans l'API People. Par exemple, si la valeur de l'API People person resourceName est people/123456789, définissez membership.member.name sur users/123456789.
    • ID de l'utilisateur dans l'API Directory.
    • Adresse e-mail de l'utilisateur. Par exemple, users/222larabrown@gmail.com ou users/larabrown@cymbalgroup.com. Si l'utilisateur utilise un compte Google ou appartient à une autre organisation Google Workspace, vous devez utiliser son adresse e-mail.

Créer une clé API

Pour appeler une méthode d'API en version Preview développeur, vous devez utiliser une version non publique de la version Preview développeur du document de découverte de l'API. Pour authentifier la requête, vous devez transmettre une clé API.

Pour créer la clé API, ouvrez le projet Google Cloud de votre application et procédez comme suit:

  1. Dans la console Google Cloud, accédez à Menu  > API et services > Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur Créer des identifiants > Clé API.
  3. Votre nouvelle clé API s'affiche.
    • Cliquez sur Copier  pour copier votre clé API et l'utiliser dans le code de votre application. La clé API se trouve également dans la section "Clés API" des identifiants de votre projet.
    • Cliquez sur Restreindre la clé pour mettre à jour les paramètres avancés et limiter l'utilisation de votre clé API. Pour en savoir plus, consultez Appliquer des restrictions de clé API.

Écrire un script qui appelle l'API Chat

L'exemple suivant ajoute un utilisateur à un espace avec une authentification d'application:

Python

  1. Dans votre répertoire de travail, créez un fichier nommé chat_membership_app_create.py.

  2. Incluez le code suivant dans chat_membership_app_create.py:

    from google.oauth2 import service_account
from apiclient.discovery import build

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.app.memberships"]

def main():
    '''
    Authenticates with Chat API using app authentication,
    then adds a user to a Chat space by creating a membership.
    '''

    # Specify service account details.
    creds = (
        service_account.Credentials.from_service_account_file('credentials.json')
        .with_scopes(SCOPES)
    )

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds, discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY')

    # Use the service endpoint to call Chat API.
    result = chat.spaces().members().create(

        # The space in which to create a membership.
        parent = 'spaces/SPACE',

        # Specify which user the membership is for.
        body = {
          'member': {
            'name':'users/USER',
            'type': 'HUMAN'
          }
        }

    ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

  3. Dans le code, remplacez les éléments suivants:

    • API_KEY: clé API que vous avez créée pour créer le point de terminaison de service de l'API Chat.

    • SPACE: nom d'un espace, que vous pouvez obtenir à partir de la méthode spaces.list dans l'API Chat ou à partir de l'URL d'un espace.

    • USER: ID utilisateur.

  4. Dans votre répertoire de travail, créez et exécutez l'exemple:

    python3 chat_membership_app_create.py

Ajouter des utilisateurs ou des groupes Google à un espace en tant qu'administrateur Google Workspace

Si vous êtes administrateur Google Workspace, vous pouvez appeler la méthode create() pour ajouter des utilisateurs, des groupes Google ou des applications Chat à n'importe quel espace de votre organisation Google Workspace.

Pour appeler cette méthode en tant qu'administrateur Google Workspace, procédez comme suit:

Pour en savoir plus et obtenir des exemples, consultez Gérer les espaces Google Chat en tant qu'administrateur Google Workspace.

Limites et points à noter