Tarefa do Apps Script

Aviso: o Application Integration já está disponível para seu projeto do Google Cloud. Agora é possível usar a Apigee Integration e o Application Integration no mesmo projeto do Google Cloud. Saiba mais

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.

Observação: a tarefa do Apps Script é um serviço global não regionalizado.

Antes de começar

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

• Ativar a API AppsScript
• Crie um ID do cliente OAuth 2.0
• Configurar um perfil de autenticação
• Verifique se o VPC Service Controls NÃO está configurado para a integração da Apigee no projeto do Google Cloud.
  Aviso: a função do Cloud não vai funcionar ou vai parar de funcionar se o VPC Service Controls estiver configurado para a integração da Apigee no Google Cloud sobre o projeto.

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 integração com a Apigee usa o perfil de autenticação para se conectar ao Google Cloud para implantar e executar o projeto do Apps Script. Para configurar um perfil de autenticação, execute as seguintes etapas:

Adicionar a tarefa do Apps Script

1. Na IU da Apigee, selecione sua organização da Apigee.
2. Clique em Desenvolver > Integrações.
3. Selecione uma integração existente ou clique em Criar integração.

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

   1. Digite um nome e uma descrição na caixa de diálogo Criar integração.
   2. Selecione uma Região para a integração na lista de regiões compatíveis.
   3. Clique em Criar.

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

4. Na barra de navegação do designer de integração, clique em +Adicionar uma tarefa/gatilho> Tarefas para conferir a lista de tarefas 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.

Observação: o mesmo usuário precisa criar o perfil de autenticação e implantar o Apps Script. Se os usuários forem diferentes, o Apps Script não será executado.

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 na Apigee.

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.

Observação: para usar uma variável de integração no seu Apps Script, você precisa adicioná-la como um parâmetro de tarefa à tarefa do Apps Script.

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

• setIntegrationVariable
• getTaskParameter

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.