Serviço avançado de grupos do Cloud Identity

Com o serviço avançado do Cloud Identity Groups (CIG), é possível usar a API CIG no Apps Script.

Observação: esse é um serviço avançado que precisa ser ativado antes do uso.

Referência

Para informações detalhadas sobre esse serviço, consulte a documentação de referência da API CIG. Assim como todos os serviços avançados no Apps Script, o serviço avançado de CIG usa os mesmos objetos, métodos e parâmetros que a API pública. Para mais informações, consulte Como as assinaturas de método são determinadas.

Exemplo de código

As funções auxiliares a seguir usam a versão v1 da API.

Criar um grupo

Para criar um Grupo do Google, chame groups.create com uma instância do novo recurso de grupo. A instância do grupo precisa incluir um groupKey, parent e label definidos como cloudidentity.googleapis.com/groups.discussion_forum. Também é necessário definir o parâmetro initialGroupConfig, que define o proprietário inicial do grupo. É possível usar os seguintes valores para esse parâmetro:

WITH_INITIAL_OWNER: torna a pessoa que envia a solicitação proprietária do grupo.

EMPTY: cria um grupo sem proprietários iniciais. Você só pode usar esse valor se for um superadministrador ou administrador de grupos do Google Workspace. Para mais informações sobre as funções do Google Workspace, consulte funções de administrador predefinidas.

O exemplo a seguir mostra como criar um grupo em que o usuário é o proprietário:

const groups = CloudIdentityGroups.Groups;

function createGroup(groupId, parentId, displayName) {
  const groupKey = { id: groupId };
  const group = {
    parent: "customerId/" + parentId,
    displayName: displayName,
    groupKey: groupKey,
    // Set the label to specify creation of a Google Group.
    labels: { "cloudidentity.googleapis.com/groups.discussion_forum": "" },
  };
  const optionalArgs = { initialGroupConfig: "WITH_INITIAL_OWNER" };

  try {
    const response = groups.create(group, optionalArgs);
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}

Pesquisar um grupo

Para pesquisar um Grupo do Google, chame groups.search com uma string de consulta. Para pesquisar todos os grupos, forneça o label cloudidentity.googleapis.com/groups.discussion_forum.

const groups = CloudIdentityGroups.Groups;

function searchGroup(customer_id) {
  const search_query = `parent=='customerId/${customer_id}' && 'cloudidentity.googleapis.com/groups.discussion_forum' in labels`;
  const search_group_request = groups.search({ query: search_query });
  console.log(JSON.stringify(search_group_request));
}

Adicionar uma assinatura a um grupo

Você pode criar assinaturas para um grupo depois de criá-lo. Esse método exige um recurso membership e a string name do recurso pai. O primeiro valor pode ser obtido pesquisando o grupo pelo método lookup.

O método auxiliar a seguir mostra um exemplo de como adicionar uma associação a um grupo. expiryDetail é um campo opcional que pode ser adicionado para definir uma validade da assinatura. O valor de preferredMemberKey é o endereço de e-mail do membro.

const groups = CloudIdentityGroups.Groups;

function createMembership(namespace, groupId, memberKey) {
  try {
    // Given a group ID and namespace, retrieve the ID for parent group
    const groupLookupResponse = groups.lookup({
      'groupKey.id': groupId,
      'groupKey.namespace': namespace
    });
    const groupName = groupLookupResponse.name;

    // Create a membership object with a memberKey and a single role of type MEMBER
    const membership = {
      preferredMemberKey: { id: memberKey },
      roles: [
        {
          name: "MEMBER",
          expiryDetail: {
            expireTime: "2025-10-02T15:01:23Z",
          },
        },
      ],
    };

    // Create a membership using the ID for the parent group and a membership object
    const response = groups.Memberships.create(membership, groupName);
    console.log(JSON.stringify(response));
  } catch (e) {
    console.error(e);
  }
}

Receber assinaturas de um membro

Use o método groups.memberships.searchDirectGroups para pesquisar os responsáveis imediatos de um membro.

O método auxiliar a seguir mostra um exemplo de iteração pelas assinaturas diretas de um determinado membro.

const groups = CloudIdentityGroups.Groups;

 function searchMemberMemberships(memberId, pageSize) {
  try {
    let memberships = [];
    let nextPageToken = '';
    const withinParent = 'groups/-';  // This parameter sets the scope as "all groups"

    do {
      // Get page of memberships
      const queryParams = {
        query: `member_key_id == \'${memberId}\'`,
        page_size: pageSize,
        page_token: nextPageToken,
      };
      const response = groups.Memberships.searchDirectGroups(withinParent, queryParams);
      memberships = memberships.concat(response.memberships);

      // Set up next page
      nextPageToken = response.nextPageToken;
    } while (nextPageToken);

    return memberships;
  } catch(e) {
    console.error(e);
  }
}

Receber assinaturas de um grupo

Use o método groups.memberships.list para listar os membros de um grupo.

groupId: o ID numérico do grupo cujos membros você quer listar. Para encontrar o ID de um único grupo, use o método groups.lookup. Para conferir todos os IDs de grupo em um cliente ou namespace, use o método groups.list.

const groups = CloudIdentityGroups.Groups;

function listGroupMemberships(groupId, pageSize) {
  try {
    let membershipList = [];
    let nextPageToken = '';

    // Get group name
    const groupName = groups.lookup({'groupKey.id': groupId}).name;

    do {
      // Get page of memberships
      const queryParams = {
        pageSize: pageSize,
        pageToken: nextPageToken
      }
      const response = groups.Memberships.list(groupName, queryParams);
      membershipList = membershipList.concat(response.memberships);

      // Set up next page
      nextPageToken = response.nextPageToken;
    } while(nextPageToken);

    return membershipList;
  } catch (error) {
    console.error(error);
  }
}