Consulte os conectores compatíveis com a integração de aplicativos.

Tarefa do Apps Script

A tarefa do Apps Script permite executar o Google Apps Script na sua integração. O Google Apps Script é uma plataforma de desenvolvimento rápido de aplicativos que facilita e agiliza a criação de aplicativos empresariais. Para mais informações, consulte Google Apps Script. Essa tarefa é útil quando você quer executar scripts personalizados ou reutilizar os scripts atuais na sua integração.

Antes de começar

Antes de usar a tarefa do Apps Script, siga estas etapas:

Ativar a API AppsScript

Ative a API AppsScript no projeto do Google Cloud e sua conta de usuário do AppsScript para usar essa tarefa. Para mais informações sobre como ativar a API AppsScript no projeto do Google Cloud, consulte Como ativar uma API em um projeto padrão do projeto do Google Cloud. Para ativar a API na sua conta de usuário, clique em Configurações e defina Google Apps Script API como On.

Crie um ID do cliente OAuth 2.0

Se você tiver um ID do cliente do OAuth 2.0 disponível, pule esta etapa e prossiga para Configurar um perfil de autenticação.

Para informações sobre como criar um novo ID do cliente do OAuth, consulte Criar um ID do cliente OAuth.

Configurar um perfil de autenticação

A Application Integration usa o perfil de autenticação para se conectar ao Google Cloud para implantação e que executa o projeto do Apps Script. Para configurar um perfil de autenticação, execute as seguintes etapas:

Adicionar a tarefa do Apps Script

  1. No console do Google Cloud, acesse a página Application Integration.

    Acessar o Application Integration

  2. No menu de navegação, clique em Integrações.

    A página Integrations aparece listando todas as integrações disponíveis no projeto do Google Cloud.

  3. Selecione uma integração ou clique em Criar integração para criar uma nova.

    Caso você esteja criando uma nova integração, siga estas etapas:

    1. Insira um nome e uma descrição no painel Criar integração.
    2. Selecione uma região para a integração.
    3. Selecione uma conta de serviço para a integração. É possível mudar ou atualizar os detalhes da conta de serviço de uma integração a qualquer momento no painel Resumo da integração na barra de ferramentas de integração.
    4. Clique em Criar.

    Isso abre a integração na página do editor de integração.

  4. Na barra de navegação do editor de integração, clique em Tarefas para conferir a lista de tarefas e conectores disponíveis.
  5. Clique e coloque o elemento Apps Script no editor de integração.

Criar um perfil de autenticação

  1. Clique no elemento Apps Script no designer para ver o painel de configuração de tarefas do Apps Script.
  2. No painel de configuração da tarefa do Apps Script, clique em +Novo perfil de autenticação.
  3. Na caixa de diálogo Perfil de autenticação, insira um nome e uma descrição para o perfil e defina as seguintes propriedades:
    • Tipo de autenticação: selecione o código de autorização OAuth 2.0
    • Endpoint de autenticação: insira https://accounts.google.com/o/oauth2/auth
    • Endpoint do token: insira https://oauth2.googleapis.com/token
    • ID do cliente: insira o ID do cliente.

      O ID do cliente está disponível no painel do projeto do Google Cloud em Credenciais > IDs do cliente OAuth 2.0.

    • Secret: insira a chave secreta do cliente

      O secret do cliente está disponível no painel do projeto do Google Cloud em Credenciais > IDs do cliente OAuth 2.0.

    • Escopo(s): insira o seguinte:

      https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

      Observação: é possível separar vários escopos por um único caractere de espaço (" ").

  4. Clique em Gerar token de acesso e salvar.

    Você será redirecionado para uma tela de autorização. Faça login e dê consentimento às permissões listadas na tela para gerar seu token de acesso. Se a geração do token de acesso for bem-sucedida, seu perfil de autenticação será salvo e você poderá continuar editando a integração.

Configurar a tarefa do Apps Script

Para configurar um projeto do Apps Script na tarefa do Apps Script, execute as seguintes etapas:

  1. No painel de configuração da tarefa, clique em Configurar projeto do Apps Script.

    A caixa de diálogo Configuração do Apps Script será exibida.

  2. Você pode vincular um projeto atual do Apps Script ou criar um novo.

    A configuração de um projeto do Apps Script associa o projeto do Apps Script à sua integração no Application Integration.

  3. Clique em "Salvar".
  4. Clique em Open Apps Script Project.

    No editor do Apps Script, é possível ver os seguintes arquivos:

    • Run.gs: contém o código executável. Escreva o script dentro da função run. Essa função é chamada quando a tarefa do Apps Script é executada. No seu script, use as variáveis definidas no nível de integração. Para informações sobre como usar as variáveis de integração, consulte Como usar variáveis de integração.
    • Main.gs: contém o código de inicialização para executar o Apps Script a partir da sua integração. Não edite nem modifique esse arquivo.
    • Test.gs: contém o código executável para execuções de teste. É possível escrever o script dentro da função testRun para testá-lo.

    Implante o projeto no formato de apps da Web. Para mais informações sobre os vários modos de implantação, consulte Criar e gerenciar implantações.

Acessar variáveis de integração

A tarefa do Apps Script usa a biblioteca AppsScriptTask, que permite usar variáveis de integração no seu script. A biblioteca AppsScriptTask é importada automaticamente e está disponível para uso na função run.

Para acessar uma variável de integração no Apps Script, você precisa transmiti-la na forma de parâmetros de tarefa para a tarefa do Apps Script. Os parâmetros de tarefa são pares de chave-valor em que Key é o nome da variável na tarefa do AppsScript e Value é o nome da variável de integração correspondente. É possível adicionar um ou mais parâmetros de tarefa na seção Parâmetros de tarefa do painel de configuração da tarefa.

Por exemplo, se você tiver uma variável de integração chamada Produto que quer usar no Apps Script, defina Chave como ProductKey e o valor como Produto. No Apps Script, use AppsScriptTask.getTaskParameter('ProductKey') para ler a variável Produto.

A biblioteca AppsScriptTask fornece os seguintes métodos para acessar as variáveis de integração:

Nome da função Descrição Uso

setIntegrationVariable

 Define o valor fornecido para a variável.

Sintaxe: setIntegrationVariable(value,value)

Exemplo: 

// Write to an Integer variable
AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');

getTaskParameter

 Obtém o valor de uma variável.

Sintaxe: getTaskParameter(value)

Exemplo: 

// Read an integration variable
AppsScriptTask.getTaskParameter('EmployeeIDKey');

Para ver todas as funções disponíveis na biblioteca AppsScriptTaskTest, passe o cursor sobre o item de menu AppsScriptTaskTest no editor do Apps Script e clique em Mais > Abrir em uma nova guia.

Testar seu Apps Script

Antes de publicar a integração, teste o script usando a função testRun disponível no arquivo Test.gs. Escreva seu código de teste na função testRun usando a biblioteca AppsScriptTaskTest. Essa biblioteca permite executar casos de testes baseados em declarações e é importado automaticamente para uso na função testRun.

Para ver todas as funções disponíveis na biblioteca AppsScriptTaskTest, passe o cursor sobre o item de menu AppsScriptTaskTest no editor do Apps Script e clique em Mais > Abrir em uma nova guia.

A amostra a seguir mostra o uso das funções da biblioteca AppsScriptTaskTest.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

O exemplo a seguir mostra como acessar variáveis JSON e de matriz no método testRun: 

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);


  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

Depois de executar os casos de teste, é possível visualizar as declarações no Registro de execução. Para visualizar os registros, clique em Registro de execução no menu.

Práticas recomendadas

Não recomendamos o uso da tarefa do Apps Script se você precisar de latência de menos de um a dois segundos para a tarefa na integração.

Além disso, recomendamos codificar toda a lógica em uma única tarefa do Apps Script, em vez de encadear várias tarefas do Apps Script para minimizar os gargalos de desempenho.

Para informações sobre os limites de uso que se aplicam à tarefa do Apps Script, consulte Limites de uso.

Considerações

Ao incluir a tarefa do Apps Script no design de integração, considere as seguintes limitações do sistema:

  • Máximo de implantações ativas para um AppsScript: 50
  • Consultas por segundo (QPS) para executáveis da API: 5.000/min
  • Consultas por segundo (QPS) para implantações do Webapp: 5.000/min
  • Latência para executáveis da API: 1,5 s
  • Latência para apps da Web: 2,5 s
  • Tamanho máximo cumulativo de todas as variáveis de integração em um AppsScript: 15 MB

Estratégia de solução de erros

A estratégia de solução de erros para uma tarefa especifica a ação a ser realizada se a tarefa falhar devido a um erro temporário. Para mais informações sobre como usar uma estratégia de tratamento de erros e conhecer os diferentes tipos de estratégias de tratamento de erros, consulte Estratégias de tratamento de erros.

Exclusões do SLA

A tarefa do Apps Script depende do produto Google Apps Script. Como essa dependência é externa à integração de aplicativos, todas as execuções de integrações active que falham devido à falha na tarefa do Apps Script são excluídas dos termos e condições do Contrato de nível de serviço (SLA) da integração de aplicativos.

Cotas e limites

Para informações sobre o assunto, consulte Cotas e limites.

A seguir