Consulta i connettori supportati per Application Integration.

Attività della funzione Cloud Functions

L'attività Funzione cloud ti consente di configurare ed eseguire le funzioni Google Cloud dall'integrazione. Google Cloud Functions è una soluzione di calcolo leggera che consente agli sviluppatori di creare funzioni autonome a uso specifico, che rispondono a eventi Cloud senza la necessità di gestire un server o un ambiente di runtime.

Per saperne di più, consulta la documentazione di Google Cloud Functions.

Prima di iniziare

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

  1. Abilita l'API Cloud Functions (cloudfunctions.googleapis.com).

    Abilita l'API Cloud Functions

  2. Assegna i seguenti ruoli IAM all'entità:
    • Cloud Functions Admin (roles/cloudfunctions.admin)
    • Application Integration Editor (roles/integrations.integrationEditor)
    • Utente dell'account di servizio (roles/iam.serviceAccountUser)

    Per informazioni sulla concessione dei ruoli alle entità, consulta Concedere, modificare e revocare l'accesso.

  3. Per connetterti alle funzioni Cloud Run, assicurati di aver creato un profilo OAuth 2.0 o di aver allegato un account di servizio gestito dall'utente all'integrazione:
    • Se all'integrazione è associato un account di servizio, assegna a questo account il ruolo IAM Invoker di Cloud Functions.

      Per informazioni sulla concessione di ruoli a un account di servizio, vedi Gestire l'accesso agli account di servizio.

    • L'attività Funzione cloud supporta solo i profili di autenticazione di tipo Token ID OIDC di Google. Crea un profilo di autenticazione di tipo Token ID OIDC di Google utilizzando l'account di servizio a cui è stato assegnato il ruolo IAM Approvatore di funzioni cloud. Se l'attività Funzione cloud 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 sono configurati né il profilo ID OIDC né l'account di servizio gestito dall'utente, viene utilizzato l'account di servizio predefinito (service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com) per chiamare l'attività Cloud Function.

  4. Assicurati che i Controlli di servizio VPC NON siano configurati per l'Application Integration nel tuo progetto Google Cloud.

Configura l'attività della Cloud Function

Per configurare l'attività funzione Cloud Functions nell'integrazione, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Integrazione delle applicazioni.

    Vai ad Application Integration

  2. Nel menu di navigazione, fai clic su Integrations (Integrazioni).

    Viene visualizzata la pagina Integrazioni, che elenca tutte le integrazioni disponibili nel progetto Google Cloud.

  3. Seleziona un'integrazione esistente o fai clic su Crea integrazione per crearne una nuova.

    Se stai creando una nuova integrazione:

    1. Inserisci un nome e una descrizione nel riquadro Crea integrazione.
    2. Seleziona una regione per l'integrazione.
    3. Seleziona un account di servizio per l'integrazione. Puoi modificare o aggiornare i dettagli dell'account di servizio di un'integrazione in qualsiasi momento dal riquadro Riepilogo dell'integrazione nella barra degli strumenti di integrazione.
    4. Fai clic su Crea.

    Viene visualizzata l'integrazione nell'editor di integrazione.

  4. Nella barra di navigazione dell'editor di integrazione, fai clic su Attività per visualizzare l'elenco di attività e connettori disponibili.
  5. Fai clic e posiziona l'elemento funzione Cloud Functions nell'Editor integrazioni.
  6. Fai clic sull'elemento Funzione cloud nel designer per aprire il riquadro di configurazione, quindi fai clic su Configura funzione cloud.
  7. Nella finestra di dialogo Configurazione di Cloud Functions, scegli una delle seguenti opzioni:
    • Collega funzione esistente. Seleziona questa opzione per collegare una Cloud Function esistente configurata nell'integrazione. Inserisci l'URL di attivazione della funzione Cloud.
    • Crea nuova funzione. Seleziona questa opzione per creare una nuova Cloud Function associata all'integrazione. Inserisci il nome della funzione cloud e seleziona la regione della funzione dall'elenco a discesa.
  8. Fai clic su Salva.

    Nel progetto Google Cloud viene creata una funzione Google Cloud di basecreata con il modello Python, associata all'integrazione. Il riquadro di configurazione della task visualizza l'URL attivatore e i parametri della task della Cloud Function.

Modello di funzione Cloud

Gli esempi riportati di seguito mostrano come utilizzare l'attività Funzione cloud nell'integrazione per lingue diverse.

Python

Quando configuri la Cloud Function utilizzando una funzione Cloud 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(**json.loads(json.htmlsafe_dumps(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

L'esempio riportato di seguito mostra come utilizzare l'attività Funzione cloud 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

L'esempio riportato di seguito mostra come utilizzare l'attività Funzione cloud nell'integrazione. Assicurati che la risposta segua il formato JSON supportato come descritto nell'esempio:

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

L'esempio riportato di seguito mostra come utilizzare l'attività Funzione cloud nell'integrazione. Assicurati che la risposta segua il formato JSON supportato come descritto nell'esempio:

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à Cloud Function

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

Per modificare un'attività Cloud Functions:

  1. Nel riquadro di configurazione dell'attività, fai clic su Apri funzione Cloud.

    Verrà visualizzata la pagina Dettagli funzione nella Google Cloud Console.

  2. Fai clic su Modifica.
  3. La pagina Configurazione ti consente di modificare le impostazioni di configurazione predefinite della Cloud Function. Per ulteriori informazioni, consulta Configurazione di Cloud Functions.
  4. Fai clic su Avanti per modificare i file di 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.
    • 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à della Cloud Function. L'oggetto event del file main.py contiene tutti i parametri dell'attività.

      Consulta Accedere alle variabili di integrazione per informazioni su come utilizzare le variabili definite a livello di integrazione nello script.

  5. Fai clic su Esegui il deployment.

Accedere alle variabili di integrazione

Per accedere a una variabile di integrazione nella funzione Cloud, devi passare la variabile sotto forma di parametri dell'attività all'attività Cloud Function. I parametri dell'attività sono coppie chiave-valore in cui Key è il nome della variabile di riferimento utilizzata nel file sorgente della Cloud Function e Value è il nome della variabile di integrazione corrispondente a cui fa riferimento la variabile di riferimento. Puoi aggiungere uno o più parametri di attività nella sezione Parametri 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 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
  newValue = 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 va a buon fine 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à della funzione Cloud ha una dipendenza dal prodotto Google Cloud Functions. Poiché questa dipendenza è esterna all'Application Integration, tutte le esecuzioni di integrazioni di active che non vanno a buon fine a causa del fallimento dell'attività della Cloud Function sono escluse dai termini e dalle condizioni dell'accordo sul livello del servizio (SLA) per l'integrazione dell'applicazione.

Quote e limiti

Per informazioni su quote e limiti, consulta Quote e limiti.

Passaggi successivi