Criar um complemento do Google Workspace com Node.js

Crie complementos do Google Workspace em funções do Cloud Run usando o ambiente de execução do Node.js.

Objetivos

Prepare o ambiente.
Crie e implemente uma função do Cloud Run.
Crie e implemente o complemento.
Instalar o complemento.

Pré-requisitos

Um projeto na nuvem do Google.
Ative o faturamento para seu projeto na nuvem. Saiba como verificar o status de faturamento dos seus projetos.
O SDK Cloud está configurado com o projeto na nuvem.

Configurar o ambiente

Abra seu projeto na nuvem no console do Google Cloud

No console do Google Cloud, acesse a página Selecionar um projeto.
Selecionar um projeto na nuvem
Selecione o projeto na nuvem do Google que você quer usar. Ou clique em Criar projeto e siga as instruções na tela. Se você criar um projeto do Google Cloud, talvez seja necessário ativar o faturamento para o projeto.

Configurar a tela de permissão OAuth

Os complementos do Google Workspace exigem uma configuração de tela de permissão. A configuração da tela de permissão OAuth do complemento define o que o Google mostra aos usuários.

No console de APIs do Google, acesse Menu > Plataforma de autenticação do Google > Branding.
Acessar o branding
Se você já configurou a plataforma de autenticação do Google, poderá configurar as seguintes configurações da tela de permissão OAuth em Branding, Público e Acesso a dados. Se você receber uma mensagem informando que a plataforma de autenticação do Google ainda não está configurada, clique em Começar:

Em Informações do app, no campo Nome do app, insira um nome para o app.
Em E-mail para suporte do usuário, escolha um endereço de e-mail de suporte para que os usuários possam entrar em contato com você se tiverem dúvidas sobre o consentimento.
Clique em Próxima.
Em Público, selecione Interno.
Clique em Próxima.
Em Informações de contato, insira um endereço de e-mail para receber notificações sobre mudanças no seu projeto.
Clique em Próxima.
Em Concluir, revise a Política de dados do usuário dos serviços de API do Google e, se concordar, selecione Concordo com a Política de dados do usuário dos serviços de API do Google.
Clique em Continuar.
Clique em Criar.

Por enquanto, você pode pular a adição de escopos. No futuro, ao criar um app para uso fora da sua organização do Google Workspace, você precisará mudar o Tipo de usuário para Externo. Em seguida, adicione os escopos de autorização necessários para o app. Para saber mais, consulte o guia completo Configurar a tela de permissão OAuth guide.

Criar e implementar uma função do Cloud Run

Clique em Autorizar para provisionar e se conectar ao Cloud Shell.

No terminal do Cloud Shell, ative a API Cloud Run functions, a API Cloud Build, a API Google Workspace add-ons, a API Compute Engine e a API Cloud Run:

gcloud services enable cloudfunctions.googleapis.com  \
                    cloudbuild.googleapis.com  \
                    gsuiteaddons.googleapis.com  \
                    compute.googleapis.com  \
                    run.googleapis.com

Clique em Abrir editor na barra de ferramentas da janela do Cloud Shell para iniciar o editor do Cloud Shell.

Esse editor de código integrado oferece a conveniência de visualizar e editar arquivos no mesmo ambiente em que os projetos são criados e implementados.

No diretório vazio, crie o arquivo function.js com o exemplo de código a seguir:

/**
 * Cloud Run function that loads the homepage for a
 * Google Workspace add-on.
 *
 * @param {Object} req Request sent from Google
 * @param {Object} res Response to send back
 */
exports.loadHomePage = function addonsHomePage (req, res) {
  res.send(createAction());
};

/** Creates a card with two widgets. */
function createAction() {
  return {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "header": {
              "title": "Cats!"
            },
            "sections": [
              {
                "widgets": [
                  {
                    "textParagraph": {
                      "text": "Your random cat:"
                    }
                  },
                  {
                    "image": {
                      "imageUrl": "https://cataas.com/cat"
                     }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  };
}

No mesmo diretório, crie o arquivo package.json com o exemplo de código a seguir:

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

Para voltar ao terminal do Cloud Shell, clique em Abrir terminal.

Adicione o papel Cloud Build Service Account (roles/cloudbuild.builds.builder) à conta de serviço padrão do Compute Engine.

Primeiro, configure a permissão da conta de serviço:

export PROJECT_ID=$(gcloud config get project)
export SERVICE_ACCOUNT_NAME=$(gcloud compute project-info describe \
  --format="value(defaultServiceAccount)")

Em seguida, conceda a permissão ausente da conta de serviço:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.builder"

Execute o seguinte comando para implementar a função:
```
gcloud run deploy loadHomePage --runtime nodejs22 --trigger-http
```
Se solicitado, especifique que você não permite invocações não autenticadas da função. A implementação da função pode levar alguns minutos.

Criar uma implantação de complemento

Encontre o e-mail da conta de serviço do complemento:
```
gcloud workspace-add-ons get-authorization
```

Conceda à conta de serviço o cloudfunctions.invoker papel. Substitua SERVICE_ACCOUNT_EMAIL pelo serviceAccountEmail campo da etapa anterior.

gcloud run services add-iam-policy-binding loadHomePage \
    --role roles/roles/run.invoker \
    --member serviceAccount:SERVICE_ACCOUNT_EMAIL

Receba o URL da função implementada. Para receber o URL, execute o comando a seguir e procure o campo url na seção httpsTrigger:
```
gcloud run services describe loadHomePage
```
Para voltar ao editor do Cloud Shell, clique em Abrir editor.

No mesmo diretório de package.json, crie o arquivo deployment.json com o exemplo de código a seguir. Substitua URL pelo url da função implementada da etapa anterior.

{
  "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"],
  "addOns": {
    "common": {
      "name": "My HTTP Add-on",
      "logoUrl": "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png",
      "homepageTrigger": {
        "runFunction": "URL"
      }
    },
    "gmail": {},
    "drive": {},
    "calendar": {},
    "docs": {},
    "sheets": {},
    "slides": {},
    "httpOptions": {
      "granularOauthPermissionSupport": "OPT_IN"
    }
  }
}

Volte ao terminal do Cloud Shell para criar a implantação:

gcloud workspace-add-ons deployments create quickstart \
    --deployment-file=deployment.json

Instalar o complemento

Instale a implantação no modo de desenvolvimento:

gcloud workspace-add-ons deployments install quickstart

Abra ou atualize o Gmail para visualizar o complemento. Na barra de ferramentas à direita, procure um ícone de béquer.
Clique no ícone para abrir o complemento. Se solicitado, autorize o complemento.

Opcional: limpar

Para evitar cobranças, exclua os recursos criados:

Desinstale o complemento da sua Conta do Google:

gcloud workspace-add-ons deployments uninstall quickstart

Para evitar cobranças pelos recursos usados neste guia de início rápido, exclua o projeto na nuvem:
```
gcloud projects delete PROJECT_ID
```
Substitua PROJECT_ID pelo ID do projeto na nuvem que você usou para o início rápido. Você pode encontrar o ID do projeto na nuvem no console de APIs do Google na página do painel.

Para adicionar mais recursos ao complemento do Google Workspace, consulte o seguinte:

Criar um complemento do Google Workspace com Node.js Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.