Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Attività della Cloud Function

L'attività funzione Cloud Functions Functions consente di configurare ed eseguire Cloud Run Functions dall'integrazione. Cloud Run Functions rappresenta la prossima evoluzione di Cloud Functions, offrendo un modello di programmazione basato su eventi con controllo e scalabilità migliorati, sfruttando la piattaforma serverless Cloud Run. Cloud Run Functions fornisce una singola soluzione serverless per tutti i tipi di workload.

L'attività funzione Cloud Functions Functions supporta le seguenti versioni di Cloud Run Functions:

Cloud Functions (1ª generazione.)
Cloud Run Functions create utilizzando l'API Cloud Functions v2

Per informazioni dettagliate sulle differenze tra le versioni di Cloud Run Functions, consulta la guida al confronto di Cloud Functions.

Prima di iniziare

Prima di configurare l'attività funzione Cloud Functions , assicurati di eseguire le seguenti attività nel tuo progetto Google Cloud.

Per connetterti alla Cloud Function Functions, assicurati di aver creato un profilo OAuth 2.0 o di aver collegato un account di servizio gestito dall'utente all'integrazione:

Se all'integrazione è collegato un account di servizio, assegna a questo account di servizio il ruolo IAM Cloud Functions Invoker.
Per informazioni sulla concessione dei ruoli a un account di servizio, consulta Gestire l'accesso agli account di servizio.
L'attività funzione Cloud Functions Functions supporta solo i profili di autenticazione di tipo token ID Google OIDC. Crea un profilo di autenticazione di tipo token ID Google OIDC utilizzando il account di servizio a cui è assegnato il ruolo IAM Cloud Functions Invoker. Se l'attività funzione Cloud Functions Functions non richiede l'autenticazione, il campo Profilo di autenticazione nel riquadro di configurazione dell'attività può essere lasciato vuoto.

Se nell'integrazione sono configurati sia il profilo ID OIDC sia un account di servizio gestito dall'utente, per impostazione predefinita viene utilizzato il profilo ID OIDC per l'autenticazione. Se non è configurato né il profilo ID OIDC né l'account di servizio gestito dall'utente, viene utilizzato il service account predefinito (service-PROJECT_NUMBER@gcp-sa-integrations.) per chiamare l'attività funzione Cloud Functions Functions.

Assicurati che i Controlli di servizio VPC non siano configurati per Application Integration nel tuo Google Cloud progetto.
Avviso: funzione Cloud Functions Functions non funziona o smette di funzionare se i Controlli di servizio VPC sono configurati per Application Integration nel tuo Google Cloud progetto.

Configurare l'attività funzione Cloud Function

Per configurare l'attività funzione Cloud Functions Functions nell'integrazione,

Nel menu di navigazione, fai clic su Integrazioni.
Viene visualizzato l'elenco delle integrazioni disponibili nell'interfaccia utente di Application Integration.
Seleziona un'integrazione esistente o fai clic su Crea integrazione.
Se stai creando una nuova integrazione, inserisci un nome e una descrizione nella finestra di dialogo di creazione e fai clic su Crea.
Dal menu a discesa Attività, fai clic su funzione Cloud Functions Functions per inserirla nell' editor di integrazione.
Fai clic sull'elemento funzione Cloud Functions Functions nel designer per aprire il riquadro di configurazione, quindi fai clic Configura funzione Cloud Functions Functions.
Se ti viene chiesto di concedere autorizzazioni al account di servizio, fai clic su Concedi.
Application Integration concede automaticamente le autorizzazioni richieste al account di servizio.
Nel riquadro Configurazione funzione Cloud Functions Functions, seleziona una delle seguenti opzioni:
- Collega funzione esistente: seleziona questa opzione per associare una funzione esistente all'integrazione. Puoi collegare Cloud Functions (1ª generazione.) e Cloud Functions create con l'API Cloud Functions v2 dall'integrazione.
  - Nel campo URL trigger funzione Cloud Functions Functions, inserisci l'URL trigger della funzione esistente.
    L'URL deve avere uno dei seguenti formati:
```
# 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
```
  Importante: assicurati che i file di origine della Cloud Function esistente rispettino il formato specificato nel modello di funzione Cloud Functions.
- Crea nuova funzione: seleziona questa opzione per creare una nuova funzione per l'integrazione.
  1. Nel campo Nome funzione, inserisci un nome univoco per la nuova funzione Cloud Run.
  2. Dal menu a discesa Regione, seleziona la regione in cui è stato eseguito il deployment di Cloud Run Functions.
  3. Dal menu a discesa Versione funzione, seleziona la versione di Cloud Run Functions che preferisci:
    - Cloud Functions (1ª gen.): questa è la versione precedente di Cloud Run Functions, nota in precedenza come Cloud Functions (1ª generazione.), che utilizza il formato dell'endpoint .cloudfunctions.net.
    - Cloud Functions (ultima gen.): questa è la versione più recente di Cloud Run Functions, creata utilizzando l'API Cloud Functions v2. Basata su Cloud Run ed Eventarc, supporta timeout delle richieste estesi (fino a 60 minuti), offre una maggiore concorrenza e utilizza i formati degli endpoint .cloudfunctions.net e .run.app.
Fai clic su Salva.

La configurazione di un'attività funzione Cloud Functions in Application Integration crea una funzione Cloud Run di base attivata da HTTP nel progetto Google Cloud.

Modello di funzione Cloud Functions

I seguenti esempi mostrano come utilizzare l'attività funzione Cloud Functions Functions nell'integrazione per diverse lingue.

Python

Quando configuri la Cloud Function utilizzando una funzione Cloud Run esistente, assicurati che i file di origine main.py, task.py e requirements.txt della funzione siano nel seguente 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

Per ulteriori informazioni sul formato della risposta, consulta ValueType.

Java

Il seguente esempio mostra come utilizzare l'attività funzione Cloud Functions Functions nell'integrazione. Assicurati che la risposta segua il formato JSON supportato come descritto nell'esempio:

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());
}

Per ulteriori informazioni sul formato della risposta, consulta ValueType.

JavaScript

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));
});

Per ulteriori informazioni sul formato della risposta, consulta ValueType.

PHP

use Psr\Http\Message\ServerRequestInterface;
function execute_function(ServerRequestInterface $request)
{
  return '{"eventParameters":{"parameters":[{"key":"input","value":{"stringValue":"2"}}]}}';
}

Per ulteriori informazioni sul formato della risposta, consulta ValueType.

Modificare un'attività funzione Cloud Function Functions

Application Integration ti indirizza alla pagina della console appropriata Google Cloud per modificare Cloud Run Functions in base al tipo di versione.

Cloud Functions (1ª generazione.)

Per modificare un'attività funzione Cloud Function Functions configurata utilizzando la versione Cloud Functions (1ª generazione.):

Nel riquadro di configurazione dell'attività, fai clic su Apri funzione Cloud Functions Functions.
Viene visualizzata la pagina Cloud Functions (1ª generazione.) > Dettagli funzione in Google Cloud console.
Fai clic su Modifica.
Nella pagina Modifica funzione, il passaggio Configurazione consente di modificare le impostazioni di configurazione predefinite della Cloud Function. Per ulteriori informazioni, consulta Configurare Cloud Functions.
Fai clic su Avanti per passare al passaggio Codice e modificare il codice sorgente della Cloud Function.
Per impostazione predefinita, la Cloud Function contiene i seguenti file di origine:
- main.py : questo file contiene il codice di inizializzazione per eseguire la Cloud Function dall'integrazione.
  Attenzione: non modificare il file main.py.
- task.py : questo file contiene il codice eseguibile della Cloud Function. Scrivi lo script all'interno della funzione run(event). Questa funzione viene chiamata quando viene eseguita l'attività funzione Cloud Function Functions. L'oggetto event del file main.py contiene tutti i parametri dell'attività.
  Per informazioni su come utilizzare le variabili definite a livello di integrazione nello script, consulta Accedere alle variabili di integrazione.
Fai clic su Esegui il deployment.

Cloud Run Functions

Per modificare un'attività funzione Cloud Function Functions configurata utilizzando la versione Cloud Functions (ultima gen.):

Nel riquadro di configurazione dell'attività, fai clic su Apri funzione Cloud Functions Functions.
Viene visualizzata la pagina Cloud Run Functions > Dettagli servizio in Google Cloud console.
Nella scheda Origine, fai clic su Modifica origine per modificare i file del codice sorgente di Cloud Run Functions.
Per impostazione predefinita, Cloud Run Functions contiene i seguenti file di origine:
- main.py : questo file contiene il codice di inizializzazione per eseguire Cloud Functions dall'integrazione.
  Attenzione: non modificare il file main.py.
- task.py: questo file contiene il codice eseguibile di Cloud Functions. Scrivi lo script all'interno della funzione run(event). Questa funzione viene chiamata quando viene eseguita l'attività Cloud Run Functions. L'oggetto event del file main.py contiene tutti i parametri dell'attività.
  Per informazioni su come utilizzare le variabili definite a livello di integrazione nello script, consulta Accedere alle variabili di integrazione.
Fai clic su Salva ed esegui di nuovo il deployment.

Accedere alle variabili di integrazione

Per accedere a una variabile di integrazione nella Cloud Function, passa la variabile come parametro dell'attività all'attività funzione Cloud Functions Functions. Il parametro dell'attività è una coppia chiave-valore in cui Chiave è il nome della variabile di riferimento utilizzata nel file di origine della funzione Cloud Function e Valore è il nome della variabile di integrazione corrispondente a cui punta la variabile di riferimento. Puoi aggiungere uno o più parametri dell'attività nella sezione Parametri dell'attività del riquadro di configurazione dell'attività.

I seguenti metodi vengono utilizzati per accedere alle variabili di integrazione dalla Cloud Function:

set: scrive il valore in una variabile.
get: legge il valore di una variabile.

Ad esempio, se hai una variabile di integrazione denominata EmployeeName che vuoi utilizzare nel file di origine della funzione Cloud Function, definisci i seguenti parametri dell'attività:

Chiave: EmployeeKey
Valore: EmployeeName

Il seguente script di esempio mostra l'utilizzo delle funzioni set e get per accedere alle variabili di integrazione definite.

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

Strategia di gestione degli errori

Una strategia di gestione degli errori per un'attività specifica l'azione da intraprendere se l'attività non riesce a causa di un errore temporaneo. Per informazioni su come utilizzare una strategia di gestione degli errori e sui diversi tipi di strategie di gestione degli errori, consulta Strategie di gestione degli errori.

Esclusioni SLA

L'attività funzione Cloud Functions Functions ha una dipendenza da il Google Cloud Functions prodotto. Poiché questa dipendenza è esterna ad Application Integration, tutte le esecuzioni di active integrazioni che non riescono a causa dell'errore nell'attività funzione Cloud Function Functions sono escluse dai termini e dalle condizioni dell'Application Integration accordo sul livello del servizio (SLA).

Quote e limiti

L'attività funzione Cloud Functions Functions ha un limite di timeout di esecuzione di 2 minuti (120 secondi). Se la funzione chiamata impiega più di 2 minuti per completare e rispondere, l'attività non riesce con un errore di timeout di esecuzione (TIMEOUT_WEB).

Attenzione: anche se la funzione Cloud Run sottostante è configurata con un timeout della richiesta più lungo (ad es. fino a 60 minuti) o l'integrazione viene eseguita con una strategia di esecuzione asincrona (ASYNC), l'attività funzione Cloud Functions Functions attende in modo sincrono la risposta HTTP e va in timeout dopo 2 minuti.

Se il tuo workload richiede tempi di esecuzione superiori a 2 minuti, valuta le seguenti soluzioni alternative:

Trigger asincrono utilizzando Pub/Sub: utilizza un'attività o un connettore Pub/Sub nell'integrazione per pubblicare un messaggio di evento e configura Cloud Run Functions in modo che venga attivata in modo asincrono dalla sottoscrizione all'argomento Pub/Sub per elaborare il workload in background.
Riconoscimento HTTP immediato e callback asincrono: configura Cloud Run Functions attivate da HTTP in modo che restituiscano una risposta HTTP 200 OK immediata alla ricezione della richiesta, elaborino l'attività a lunga esecuzione in modo asincrono in background e, facoltativamente, chiamino un endpoint trigger dell'API Application Integration per riprendere i passaggi di integrazione downstream al termine dell'elaborazione.

Per informazioni sulle quote e sui limiti generali per Cloud Run Functions e Cloud Functions (1ª generazione.), consulta Confronto tra le configurazioni.

Passaggi successivi

Scopri di più su tutte le attività e i trigger.
Scopri come testare e pubblicare un'integrazione .

Scopri di più sulla gestione degli errori.
Scopri di più sui log di esecuzione dell'integrazione.