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é à participer à 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 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} est 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 éléments suivants 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.

Écrire un script qui appelle l'API Chat

L'exemple suivant ajoute un utilisateur à un espace avec l'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)

    # 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 :

    • 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