Consulte os conetores suportados para a solução Application Integration.
Tarefa do Apps Script
A tarefa do Apps Script permite-lhe executar o Google Apps Script a partir da sua integração. O Google Apps Script é uma plataforma de programação rápida de aplicações que agiliza e simplifica a criação de aplicações empresariais. Para mais informações, consulte o Google Apps Script. Esta tarefa é útil quando quer executar scripts personalizados ou reutilizar scripts existentes na sua integração.
Antes de começar
Antes de usar a tarefa do Apps Script, certifique-se de que conclui os seguintes passos:
- Ative a API Google Apps Script
- Crie um ID de cliente OAuth 2.0
- Configure um perfil de autenticação
- Certifique-se de que o VPC Service Controls NÃO está configurado para a integração de aplicações no seu Google Cloud projeto.
Ative a API Google Apps Script
Tem de ativar a API Apps Script no seu projeto do Google Cloud e na sua conta de utilizador do Apps Script para
usar esta tarefa. Para obter informações sobre como ativar a API Apps Script no seu projeto do Google Cloud,
consulte o artigo Ativar uma API num projeto padrão do Google Cloud.
Para ativar a API na sua conta de utilizador, clique em Definições e defina
Google Apps Script API
como On
.
Crie um ID de cliente OAuth 2.0
Se tiver um ID de cliente OAuth 2.0 disponível, pode ignorar este passo e avançar para Configurar um perfil de autenticação.
Para obter informações sobre como criar um novo ID de cliente OAuth, consulte o artigo Crie um ID de cliente OAuth.
Configure um perfil de autenticação
A integração de aplicações usa o perfil de autenticação para se ligar ao Google Cloud para implementar e executar o projeto do Apps Script. Para configurar um perfil de autenticação, siga estes passos:
Adicione a tarefa do Apps Script
- Na Google Cloud consola, aceda à página Application Integration.
- No menu de navegação, clique em Integrações.
A página Integrações é apresentada com todas as integrações disponíveis no projeto do Google Cloud.
- Selecione uma integração existente ou clique em Criar integração para criar uma nova.
Se estiver a criar uma nova integração:
- Introduza um nome e uma descrição no painel Criar integração.
- Selecione uma região para a integração.
- Selecione uma conta de serviço para a integração. Pode alterar ou atualizar os detalhes da conta de serviço de uma integração em qualquer altura no painel Resumo da integração na barra de ferramentas de integração.
- Clique em Criar. A integração recém-criada é aberta no editor de integração.
- Na barra de navegação do editor de integração, clique em Tasks para ver a lista de tarefas e conetores disponíveis.
- Clique e coloque o elemento Apps Script no editor de integração.
Crie um perfil de autenticação
- Clique no elemento Apps Script no criador para ver o painel de configuração da tarefa Apps Script.
- No painel de configuração de tarefas da tarefa do Apps Script, clique em + Novo perfil de autenticação.
- Na caixa de diálogo Perfil de autenticação, introduza um nome e uma descrição para o perfil e defina as seguintes propriedades:
- Tipo de autenticação: selecione Código de autorização OAuth 2.0
- Ponto final de autenticação: introduza
https://accounts.google.com/o/oauth2/auth
- Ponto final do token: introduza
https://oauth2.googleapis.com/token
- ID de cliente: introduza o ID de cliente.
O ID de cliente está disponível no painel de controlo do seu projeto do Google Cloud em Credenciais > IDs de clientes OAuth 2.0.
- Segredo: introduza o segredo do cliente
O segredo do cliente está disponível no painel de controlo do seu projeto do Google Cloud em Credenciais > IDs de cliente OAuth 2.0.
- Âmbito(s): introduza 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
Nota: pode separar vários âmbitos com um único espaço (" ").
- Clique em Gerar token de acesso e guardar.
É feito o redirecionamento para um ecrã de autorização. Inicie sessão e dê o seu consentimento para as autorizações apresentadas no ecrã para gerar o seu token de acesso. Se a geração do token de acesso for bem-sucedida, o seu perfil de autenticação é guardado e pode continuar a editar a integração.
Configure a tarefa do Apps Script
Para configurar um projeto do Apps Script na tarefa Apps Script, siga estes passos:
- No painel de configuração da tarefa,
clique em Configurar projeto do Apps Script.
É apresentada a caixa de diálogo Configuração do Apps Script.
- Pode optar por associar a um projeto do Apps Script existente ou criar um novo projeto do Apps Script.
A configuração de um projeto do Apps Script associa o projeto do Apps Script à sua integração no Application Integration.
- Clique em Guardar.
- Clique em Abrir projeto do Apps Script.
No editor do Apps Script, pode ver os seguintes ficheiros:
Run.gs
: contém o código executável. Escreva o seu script dentro da funçãorun
. Esta função é chamada quando a tarefa do Apps Script é executada. No script, pode usar as variáveis definidas ao nível da integração. Para obter informações sobre a utilização das variáveis de integração, consulte o artigo 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 este ficheiro.Test.gs
: contém o código executável para execuções de testes. Pode escrever o script na funçãotestRun
para testar o script.
Certifique-se de que implementa o projeto no formato de apps Web. Para mais informações sobre os vários modos de implementação, consulte o artigo Crie e faça a gestão de implementações.
Aceda às variáveis de integração
A tarefa do Apps Script usa a biblioteca AppsScriptTask, que lhe permite
usar variáveis de integração no seu script. A biblioteca AppsScriptTask
é importada automaticamente e está disponível para utilização na função run
.
Para aceder a uma variável de integração no Apps Script, tem de transmitir a variável no formato de parâmetros de tarefas para a tarefa do Apps Script. Os parâmetros da tarefa são pares de chave-valor em que Chave é o nome da variável na sua tarefa do Apps Script e Valor é o nome da variável de integração correspondente. Pode adicionar um ou mais parâmetros de tarefas na secção Parâmetros de tarefas do painel de configuração de tarefas.
Por exemplo, se tiver uma variável de integração denominada Produto que queira usar no Apps Script, pode definir Chave como ProductKey e o valor como Produto. No
Apps Script, pode usar AppsScriptTask.getTaskParameter('ProductKey')
para ler a variável Product.
A biblioteca AppsScriptTask fornece os seguintes métodos para aceder às variáveis de integração:
Nome da função | Descrição | Utilização | |
---|---|---|---|
|
Define o valor fornecido para a variável. |
Sintaxe: Exemplo: // Write to an Integer variable AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456'); |
|
|
Obtém o valor de uma variável. |
Sintaxe: Exemplo: // Read an integration variable AppsScriptTask.getTaskParameter('EmployeeIDKey'); |
Para ver todas as funções disponíveis na biblioteca AppsScriptTask, passe o cursor do rato sobre o item de menu AppsScriptTask no editor do Apps Script, clique em Mais
> Abrir num novo separador.Teste o seu Apps Script
Antes de publicar a integração, pode testar o script com a função testRun disponível no ficheiro Test.gs. Escreva o código de teste na função testRun, usando a biblioteca AppsScriptTaskTest. Esta biblioteca permite-lhe executar casos de teste baseados em afirmações e é importada automaticamente para utilização na função testRun.
Para ver todas as funções disponíveis na biblioteca AppsScriptTaskTest, passe o cursor do rato sobre o item de menu AppsScriptTaskTest no editor do Apps Script, clique em Mais
> Abrir num novo separador.O exemplo seguinte mostra a utilização 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 seguinte mostra como aceder a 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 exemplos de teste, pode ver as afirmações no Registo de execução. Para ver os registos, clique em Registo de execução no menu.
Práticas recomendadas
Não recomendamos a utilização da tarefa do Apps Script se precisar de uma latência inferior a 1 a 2 segundos para a tarefa na sua integração.
Além disso, recomendamos que codifique toda a lógica numa única tarefa do Apps Script, em vez de encadear várias tarefas do Apps Script, para minimizar os gargalos de desempenho.
Para obter informações sobre os limites de utilização que se aplicam à tarefa do Apps Script, consulte Limites de utilização.
Considerações
Quando incluir a tarefa do Apps Script na estrutura da integração, considere as seguintes limitações do sistema:
- Máximo de implementações ativas para um Apps Script: 50
- Consultas por segundo (CPS) para executáveis da API: 5000/min
- Consultas por segundo (CPS) para implementações de apps Web: 5000/min
- Latência para executáveis de API: 1,5 s
- Latência da app Web: 2,5 s
- Tamanho cumulativo máximo de todas as variáveis de integração num Apps Script: 15 MB
Estratégia de processamento de erros
Uma estratégia de processamento de erros para uma tarefa especifica a ação a realizar se a tarefa falhar devido a um erro temporário. Para obter informações sobre como usar uma estratégia de processamento de erros e conhecer os diferentes tipos de estratégias de processamento de erros, consulte o artigo Estratégias de processamento de erros.
Exclusões do SLA
A tarefa do Apps Script tem uma dependência do produto Google Apps Script.
Uma vez que esta dependência é externa à integração de aplicações, 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 aplicações.
Quotas e limites
Para informações sobre quotas e limites, consulte o artigo Quotas e limites.
O que se segue?
- Saiba mais sobre todas as tarefas e acionadores.
- Saiba como testar e publicar uma integração.
- Saiba mais acerca do processamento de erros.
- Saiba mais sobre os registos de execução da integração.