Tarefa da função do Cloud
A tarefa Função do Cloud permite configurar e executar funções do Cloud Run na integração. As funções do Cloud Run representam a próxima evolução do Cloud Functions, oferecendo um modelo de programação orientado a eventos com controle e escalonabilidade aprimorados, aproveitando a plataforma sem servidor do Cloud Run. As funções do Cloud Run oferecem uma única solução sem servidor para todos os tipos de carga de trabalho.
A tarefa Função do Cloud é compatível com as seguintes versões das funções do Cloud Run:
- Cloud Functions (1ª geração)
- Funções do Cloud Run criadas usando a API Cloud Functions v2
Para informações detalhadas sobre as diferenças entre as versões das funções do Cloud Run, consulte o guia de comparação do Cloud Functions.
Antes de começar
Realize as seguintes tarefas no seu projeto na nuvem do Google Cloud antes de configurar a tarefa da função do Cloud.
- Para se conectar à função do Cloud, verifique se você criou um perfil OAuth 2.0 ou anexou uma conta serviço gerenciado pelo usuário à sua integração:
-
Se a integração tiver uma conta de serviço anexada, atribua o papel do IAM Invocador de funções do Cloud a essa conta.
Para informações sobre como conceder papéis a uma conta de serviço, consulte Gerenciar o acesso a contas de serviço.
- A tarefa Função do Cloud só aceita perfis de autenticação do tipo Token de ID do Google OIDC. Crie um perfil de autenticação do tipo Token de ID do Google OIDC usando a conta de serviço com o papel Invocador de funções do Cloud do IAM atribuído. Se a tarefa Função do Cloud não exigir autenticação, o campo Perfil de autenticação no painel de configuração da tarefa poderá ser deixado em branco.
- Verifique se o VPC Service Controls não está configurado para o Application Integration no seu Google Cloud projeto.
Se a integração tiver um perfil de ID do OIDC e uma conta de serviço gerenciado pelo usuário configurados, o perfil de ID do OIDC será usado para autenticação por padrão. Se nem o perfil de ID do OIDC nem a conta de serviço gerenciado pelo usuário estiverem configurados, a conta de serviço padrão (service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com) será usada para chamar a tarefa Função do Cloud.
Configurar a tarefa da função do Cloud
Para configurar a tarefa da função do Cloud na integração, execute as seguintes etapas:
- No menu de navegação, clique em Integrações.
Isso abre a lista de integrações disponíveis na interface do Application Integration.
- Selecione uma integração ou clique em Criar integração.
Se você estiver criando uma nova integração, digite um nome e uma descrição na caixa de diálogo de criação e clique em Criar.
- No menu suspenso Tarefas, clique em Função do Cloud para colocá-la no editor de integração.
- Clique no elemento Função do Cloud no designer para abrir o painel de configuração e clique em Configurar função do Cloud.
-
Se for necessário conceder permissões à conta de serviço, clique em
Conceder.
O Application Integration concede automaticamente as permissões necessárias à conta de serviço.
- No painel Configuração da função do Cloud, selecione uma das seguintes opções:
- Vincular existentes:selecione essa opção para associar uma função à integração. É possível vincular o Cloud Functions (1ª geração) e o Cloud Functions criados com a API Cloud Functions v2 da sua integração.
- No campo URL do gatilho da função do Cloud, insira o URL do gatilho da função atual.
O URL precisa seguir um destes formatos:
# For Cloud Functions (1st gen) https://REGION_NAME-PROJECT_ID.cloudfunctions.net/FUNCTION_NAME# For Cloud Run functions created using the Cloud Functions v2 API https://FUNCTION_NAME-PROJECT_ID.REGION_NAME.run.app
- No campo URL do gatilho da função do Cloud, insira o URL do gatilho da função atual.
- Criar nova função:selecione essa opção para criar uma nova função para a integração.
- No campo Nome da função, insira um nome exclusivo para as novas funções do Cloud Run.
- No menu suspenso Região, selecione a região em que as funções do Cloud Run estão implantadas.
- No menu suspenso Versão da função, selecione a versão desejada das funções do Cloud Run:
- Cloud Functions (1ª geração) : essa é a versão legada das funções do Cloud Run, anteriormente conhecida como Cloud Functions (1ª geração), que usa o formato de endpoint
.cloudfunctions.net. - Cloud Functions (última geração) : essa é a versão mais recente das funções do Cloud Run, criada usando a API Cloud Functions v2. Criada no Cloud Run e no Eventarc, ela oferece suporte a tempos limite de solicitação estendidos (até 60 minutos), oferece maior simultaneidade e usa os formatos de endpoint
.cloudfunctions.nete.run.app.
Para mais informações sobre as diferenças entre as duas versões, consulte Comparar o Cloud Functions.
- Cloud Functions (1ª geração) : essa é a versão legada das funções do Cloud Run, anteriormente conhecida como Cloud Functions (1ª geração), que usa o formato de endpoint
- Vincular existentes:selecione essa opção para associar uma função à integração. É possível vincular o Cloud Functions (1ª geração) e o Cloud Functions criados com a API Cloud Functions v2 da sua integração.
- Clique em Salvar.
A configuração de uma tarefa da função do Cloud no Application Integration cria uma função do Cloud Run básica acionada por HTTP- acionada no seu projeto na nuvem do Google Cloud.
Modelo de função do Cloud
Os exemplos a seguir mostram como usar a tarefa Função do Cloud na integração para diferentes linguagens.
Python
Ao configurar a função do Cloud usando uma função do Cloud Run, verifique se os arquivos de origem main.py, task.py e requirements.txt da função estão no seguinte formato:
task.py
# Sample Code: # print(event.get('task_string_key')) # event.set('task_int_array_key', [456, 789]); # event.log('some logging') def run(event): """Actual cloud function custom logic. Args: event : event object in main.py that contains all parameters. """ return
main.py
"""Un-editable platform wrapper which invokes user code.""" import traceback from flask import json from flask import jsonify from task import run VALUE_NAME = [ 'stringValue', 'intValue', 'doubleValue', 'booleanValue', 'protoValue' ] ARRAY_VALUE_NAME = { 'stringArray': 'stringValues', 'intArray': 'intValues', 'doubleArray': 'doubleValues', 'booleanArray': 'booleanValues', 'protoArray': 'protoValues' } VALUE_TYPE_URL = 'type.googleapis.com/google.protobuf.Value' CLOUD_FUNCTION_EXCEPTION_KEY = 'CloudFunctionException' CLOUD_FUNCTION_LOGGING_KEY = 'CloudFunctionLogging' class _Event(object): """Event object.""" def __init__(self, json_payload): self._event_params = json_payload.get('eventParameters', dict()) self._task_params = json_payload.get('taskParameters', dict()) self._log = [] print('Event param is ' + str(self._event_params)) print('Task param is ' + str(self._task_params)) def set(self, key, value): """Set the event parameters key-value. Args: key: parameter key. value: parameter value. """ new_param = self._create_param(key, value) param = self._get_param_by_key(key) if param is None: if 'parameters' not in self._event_params: self._event_params['parameters'] = [] self._event_params['parameters'].append(new_param) else: param['value'] = new_param['value'] def _create_param(self, key, value): """Create a new parameter with given key value pair. Args: key: parameter key. value: parameter value. Returns: parameter. """ new_param = {} new_param['key'] = key if isinstance(value, str): new_param['value'] = {'stringValue': value} elif isinstance(value, int): new_param['value'] = {'intValue': value} elif isinstance(value, float): new_param['value'] = {'doubleValue': value} elif isinstance(value, bool): new_param['value'] = {'booleanValue': value} elif isinstance(value, dict): if 'type@' in value: new_param['value'] = {'protoValue': value} else: new_param['value'] = { 'protoValue': { '@type': 'type.googleapis.com/google.protobuf.Value', 'value': value } } elif isinstance(value, list): if not value: raise RuntimeError('Cannot create a param with empty list') if any(not isinstance(val, type(value[0])) for val in value): print('Not all elements in the list have the same type') new_param['value'] = { 'protoValue': { '@type': 'type.googleapis.com/google.protobuf.Value', 'value': value } } elif isinstance(value[0], str): new_param['value'] = {'stringArray': {'stringValues': value}} elif isinstance(value[0], int): new_param['value'] = {'intArray': {'intValues': value}} elif isinstance(value[0], float): new_param['value'] = {'doubleArray': {'doubleValues': value}} elif isinstance(value[0], bool): new_param['value'] = {'booleanArray': {'booleanValues': value}} elif isinstance(value[0], dict): if all('@type' in val and val['@type'] == value[0]['@type'] for val in value): new_param['value'] = {'protoArray': {'protoValues': value}} else: new_param['value'] = { 'protoValue': { '@type': 'type.googleapis.com/google.protobuf.Value', 'value': value } } else: raise RuntimeError('The type ' + type(value[0]) + ' in the list is not supported') else: raise RuntimeError('Value ' + str(value) + ' has the type ' + type(value) + ' that is not supported') return new_param def get(self, key): """Get the event parameter value for specified key. Args: key: parameter key. Returns: Parameter value. """ param = self._get_param_by_key(key) if param is None: raise RuntimeError('Can not find param with key ' + key) return self._get_param_value(param) def _get_param_by_key(self, key): """Get the parameter for specified key. Args: key: parameter key. Returns: Parameter. """ param = self._get_param_by_key_from_params(key, self._task_params) if param is None: return self._get_param_by_key_from_params(key, self._event_params) value = self._get_param_value(param) if isinstance(value, str) and len(value) > 2 and value.startswith( '$') and value.endswith('$'): return self._get_param_by_key_from_params(value[1:-1], self._event_params) return param def _get_param_by_key_from_params(self, key, params): """Get the parameter for specified key from event parameters. Args: key: parameter key. params: event parameters. Returns: Parameter. """ if not isinstance(params, dict) or 'parameters' not in params: return None for param in params['parameters']: if param['key'] == key: return param return None def _get_param_value(self, param): """Get the parameter value for specified parameter. Args: param: parameter. Returns: Parameter value. """ value = param['value'] if len(value) != 1: raise RuntimeError('param does not have size of 1') for value_name in VALUE_NAME: if value_name in value: if value_name == 'protoValue' and value[value_name][ '@type'] == VALUE_TYPE_URL: return value[value_name]['value'] return value[value_name] for array_value_name in ARRAY_VALUE_NAME: if array_value_name in value: return value[array_value_name][ARRAY_VALUE_NAME[array_value_name]] raise RuntimeError('Cannot get value from param ' + str(param)) def set_error(self): """Set the cloud function error to event parameters in order for user to see on IP.""" self.set(CLOUD_FUNCTION_EXCEPTION_KEY, traceback.format_exc()) def log(self, message): self._log.append(str(message)) def get_response(self): """Get the response that can be returned to IP. Returns: The response text or any set of values that can be turned into a Response object using `make_response <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>`. """ if self._log: self.set(CLOUD_FUNCTION_LOGGING_KEY, self._log) res = { 'eventParameters': self._event_params, } return jsonify(res) def execute_function(request): """Entry point of the cloud function. Args: request (flask.Request): HTTP request object. Returns: The response text or any set of values that can be turned into a Response object using `make_response <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>`. """ try: request_json = request.get_json(silent=True) event = _Event(request_json) run(event) except: event.set_error() return event.get_response()
requirements.txt
# Function dependencies, for example: # package>=version
Para mais informações sobre o formato de resposta, consulte ValueType.
Java
O exemplo a seguir mostra como usar a tarefa Função do Cloud na integração. Verifique se a resposta segue o formato JSON compatível, conforme descrito no exemplo:
private static final Gson gson = new Gson(); @Override public void service(HttpRequest request, HttpResponse response) throws Exception { JsonObject body = gson.fromJson(request.getReader(), JsonObject.class); JsonArray resParams = new JsonArray(); for (JsonElement param: body.getAsJsonObject("eventParameters").getAsJsonArray("parameters")) { if (param.getAsJsonObject().get("key").getAsString().equals("input")) { JsonObject newParam= new JsonObject(); newParam.addProperty("key", "input"); JsonObject value = new JsonObject(); value.addProperty("stringValue","2"); newParam.add("value", value); resParams.add(newParam); } else { resParams.add(param); } } JsonObject parameters = new JsonObject(); parameters.add("parameters", resParams); JsonObject res = new JsonObject(); res.add("eventParameters", parameters); System.out.println(res); BufferedWriter writer = response.getWriter(); writer.write(res.toString()); }
Para mais informações sobre o formato de resposta, consulte ValueType.
JavaScript
O exemplo a seguir mostra como usar a tarefa Função do Cloud na integração. Verifique se a resposta segue o formato JSON compatível, conforme descrito no exemplo:
const functions = require('@google-cloud/functions-framework'); functions.http('execute_function', (req, res) => { console.log(JSON.stringify(req.body)); let response = {"eventParameters":{"parameters":[{"key":"input","value":{"stringValue":"2"}}]}}; res.send(JSON.stringify(response)); });
Para mais informações sobre o formato de resposta, consulte ValueType.
PHP
O exemplo a seguir mostra como usar a tarefa Função do Cloud na integração. Verifique se a resposta segue o formato JSON compatível, conforme descrito no exemplo:
use Psr\Http\Message\ServerRequestInterface; function execute_function(ServerRequestInterface $request) { return '{"eventParameters":{"parameters":[{"key":"input","value":{"stringValue":"2"}}]}}'; }
Para mais informações sobre o formato de resposta, consulte ValueType.
Editar uma tarefa da função do Cloud
O Application Integration direciona você para a página do Google Cloud console apropriada para editar as funções do Cloud Run com base no tipo de versão.
Cloud Functions (1ª geração)
Para editar uma tarefa da função do Cloud configurada usando a versão do Cloud Functions (1ª geração), siga estas etapas:
- No painel de configuração da tarefa, clique em Abrir a Função do Cloud.
Você será direcionado para a página Cloud Functions (1ª geração) > Detalhes da função no seu projeto Google Cloud console.
- Clique em Editar.
- Na página Editar função, a etapa Configuração permite editar as configurações padrão da função do Cloud. Consulte Como configurar o Cloud Functions para mais informações.
- Clique em Próxima para continuar para a etapa Código e editar o código-fonte da função do Cloud.
Por padrão, a função do Cloud contém os seguintes arquivos de origem:
- main.py : esse arquivo contém o código de inicialização para executar a função do Cloud a partir da integração.
- task.py : esse arquivo contém o código executável da função do Cloud.
Escreva o script dentro da função
run(event). Essa função é chamada quando a tarefa da função do Cloud é executada. O objetoeventdo arquivo main.py contém todos os parâmetros da tarefa.Consulte Acessar variáveis de integração para saber como usar as variáveis definidas no nível da integração no script.
- Clique em Implantar.
Cloud Run functions
Para editar uma tarefa da função do Cloud configurada usando a versão do Cloud Functions (última geração), siga estas etapas:
- No painel de configuração da tarefa, clique em Abrir a Função do Cloud.
Você será redirecionado para a página Cloud Run functions > Detalhes do serviço no seu projeto Google Cloud console.
- Na guia Origem, clique em Editar origem para editar os arquivos de código-fonte das funções do Cloud Run.
Por padrão, as funções do Cloud Run contêm os seguintes arquivos de origem:
- main.py : esse arquivo contém o código de inicialização para executar o Cloud Functions a partir da integração.
- task.py: esse arquivo contém o código executável do Cloud Functions.
Escreva o script dentro da função
run(event). Essa função é chamada quando a tarefa das funções do Cloud Run é executada. O objetoeventdo arquivo main.py contém todos os parâmetros da tarefa.Consulte Acessar variáveis de integração para saber como usar as variáveis definidas no nível da integração no script.
- Clique em Salvar e implantar novamente.
Acessar variáveis de integração
Para acessar uma variável de integração na função do Cloud, transmita a variável como parâmetro de tarefa para a tarefa Função do Cloud. O parâmetro da tarefa é um par de chave-valor, em que Chave é o nome da variável de referência usada no arquivo de origem da função do Cloud, e Valor é o nome da variável de integração correspondente que a referência aponta para. É possível adicionar um ou mais parâmetros de tarefa na seção Parâmetros de tarefa do painel de configuração da tarefa.
Os métodos a seguir são usados para acessar variáveis de integração da função do Cloud:
- set - Grava o valor como uma variável.
- get - Lê o valor de uma variável.
Por exemplo, se você tiver uma variável de integração chamada EmployeeName que queira usar no arquivo de origem da função do Cloud, defina os seguintes parâmetros de tarefa:
- Chave: EmployeeKey
- Valor: EmployeeName
O exemplo de script a seguir mostra o uso de funções "set" e "get" para acessar as variáveis de integração definidas.
def run(event): # Read the integration variable EmployeeName using the reference variable EmployeeKey value = event.get('EmployeeKey'); # Change the integration variable EmployeeName value using the reference variable EmployeeKey event.set('EmployeeKey' , 'XYZ'); # The new value of the integration variable is retained throughout the Cloud Function task. return
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 Função do Cloud tem uma dependência do
produto Google Cloud Functions.
Como essa dependência é externa ao Application Integration, todas as execuções de
active integrações que falham devido à falha na
tarefa Função do Cloud são excluídas dos
termos e condições do contrato de nível de serviço (SLA) do
Application Integration.
Cotas e limites
A tarefa Função do Cloud tem um limite de tempo limite de execução de 2 minutos (120 segundos). Se a função invocada levar mais de 2 minutos para ser concluída e responder, a tarefa falhará com um erro de tempo limite de execução (TIMEOUT_WEB).
Se a carga de trabalho exigir tempos de execução maiores que 2 minutos, considere as seguintes soluções alternativas:
- Acionador assíncrono usando o Pub/Sub:use uma tarefa ou conector do Pub/Sub na integração para publicar uma mensagem de evento e configure as funções do Cloud Run para serem acionadas de forma assíncrona na assinatura do tópico do Pub/Sub para processar a carga de trabalho em segundo plano.
- Confirmação HTTP imediata e callback assíncrono:configure as funções do Cloud Run acionadas por HTTP para retornar uma resposta HTTP
200 OKimediata ao receber a solicitação, processe a tarefa de longa duração de forma assíncrona em segundo plano e, opcionalmente, invoque um endpoint de acionador da API Application Integration para retomar as etapas de integração downstream após a conclusão do processamento.
Para informações sobre cotas e limites gerais para funções do Cloud Run e Cloud Functions (1ª geração), consulte Comparação de configuração.
A seguir
- Saiba mais sobre todas as tarefas e acionadores.
- Saiba como testar e publicar uma integração.
- Saiba mais sobre o tratamento de erros.
- Saiba mais sobre os registros de execução de integração.