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, ce qui revient à créer un membre. Lorsque vous créez un abonnement, si le membre spécifié a désactivé sa règle d'acceptation automatique, il est invité et doit accepter l'invitation à l'espace avant de le rejoindre. Sinon, la création d'un membre l'ajoute 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 n'y est pas.

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 informations suivantes 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'adhésion.
  • Transmettez membership en tant qu'instance de Membership avec son champ member défini sur les valeurs suivantes :
    • Le champ type défini sur HUMAN.
    • Le champ name est défini sur users/{user}, où {user} correspond à la personne que vous souhaitez ajouter à l'espace. Pour spécifier l'utilisateur Chat, remplacez {user} par l'une des options suivantes :
      • ID de la personne dans l'API People. Par exemple, si resourceName person de l'API People 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 de l'utilisateur :

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 qui a été créée.

Inviter ou ajouter un groupe Google à un espace

Pour inviter ou ajouter un groupe Google à un espace avec authentification utilisateur (l'authentification d'application ne permet pas d'inviter ni d'ajouter 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'adhésion.
  • Transmettez membership en tant qu'instance de Membership avec le champ name de groupMember défini sur groups/{group}, où {group} est l'ID du 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.

Les groupes Google ne peuvent pas être ajoutés à une discussion de groupe ni à un message privé, mais uniquement à un espace nommé.

L'exemple suivant ajoute un groupe à un espace nommé avec authentification de l'utilisateur :

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 qui a été 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 humains, transmettez les informations suivantes dans votre requête avec authentification de l'utilisateur (l'authentification de l'application ne permet pas d'inviter ni d'ajouter 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'adhésion.
  • Transmettez membership en tant qu'instance de Membership avec son champ member défini sur les valeurs suivantes :
    • Le champ type défini sur BOT.
    • Le champ name est défini sur users/app, un alias qui représente l'application appelant 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'espace name. 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 qui a été créée.

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

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

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 ressource de l'espace dans lequel créer l'abonnement.
  • Définissez member sur users/{user}, où {user} est la personne pour laquelle vous souhaitez créer un abonnement. Il peut s'agir de l'une des valeurs suivantes :
    • ID de la personne dans l'API People. Par exemple, si resourceName person de l'API People 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 de l'API Developer Preview, vous devez utiliser une version Developer Preview non publique 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 est également disponible 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 l'authentification de l'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 générer le point de terminaison de service pour l'API Chat.

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

    • USER : ID utilisateur.

  4. Dans votre répertoire de travail, compilez 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