Consulta i connettori supportati per Application Integration.

Attività connettori

L'attività Connettori ti consente di connetterti in modo rapido e sicuro ai vari servizi Google Cloud e ad altre applicazioni aziendali dalla tua integrazione utilizzando i connettori predefiniti disponibili in Integration Connectors.

Per l'elenco di tutti i connettori supportati per Application Integration, consulta Riferimento ai connettori.

Importante:Integration Connectors è un componente fatturabile di Google Cloud. Per informazioni sui costi e gli addebiti relativi all'utilizzo di Integration Connectors, consulta la pagina Prezzi di Integration Connectors.

Prima di iniziare

• Assicurati di disporre del ruolo IAM Amministratore connettori (roles/connectors.admin) concesso nel tuo progetto Google Cloud. Per informazioni sulla concessione dei ruoli, vedi Gestire l'accesso.
• Scopri i concetti generali di Integration Connectors.
• Per connetterti ai servizi Google Cloud e ad altre applicazioni aziendali utilizzando un connettore, assicurati di aver collegato un service account gestito dall'utente all'integrazione. Se l'integrazione non ha configurato un account di servizio gestito dall'utente, per l'autenticazione viene utilizzato per impostazione predefinita il service account predefinito ([e-mail]).
• Assicurati che il account di servizio disponga del ruolo IAM richiesto. Per informazioni sulla concessione dei ruoli a un account di servizio, vedi Gestire l'accesso ai service account.

Aggiungere un'attività Connettori

Per aggiungere l'attività Connettori all'integrazione:

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

   Vai ad Application Integration

2. Nel menu di navigazione, fai clic su 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.
      Nota:il menu a discesa Regioni elenca solo le regioni di cui è stato eseguito il provisioning nel tuo progetto Google Cloud. Per eseguire il provisioning di una nuova regione, fai clic su Attiva regione. Per ulteriori informazioni, consulta Attivare una nuova regione.
   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 integrazione nella barra degli strumenti dell'integrazione.
      Nota:l'opzione per selezionare un account di servizio viene visualizzata solo se hai attivato la governance dell'integrazione per la regione selezionata.
   4. Fai clic su Crea. L'integrazione appena creata si apre nell'editor integrazioni.

4. Nella barra di navigazione dell'Editor integrazioni, fai clic su Attività per visualizzare l'elenco delle attività e dei connettori disponibili.



5. Se vuoi configurare una nuova connessione, fai clic sull'elemento Connettori e posizionalo nell'Editor integrazioni. Poi, fai clic su Configura connettore per configurare la connessione.

   

6. Se hai una connessione esistente, fai clic sulla scheda Connettori per visualizzare le connessioni create di recente. Puoi anche cercare un connettore, una connessione o un'attività inserendo il nome nel campo Cerca.

   

7. Fai clic sull'elemento Connettori configurato e posizionalo nell'Editor integrazioni. Per informazioni su come configurare un'attività del connettore, consulta Configurare l'attività Connettori.

Configura l'attività Connettori

Per configurare un'attività Connettori:

Nota:i dettagli di configurazione, come l'autenticazione, variano a seconda del tipo di connessione.

1. Fai clic sull'elemento attività Connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connettori.

   (Facoltativo) Fai clic su per rinominare il nome dell'attività.

2. Fai clic su Configura connettore.
3. Puoi selezionare una connessione esistente nella regione o crearne una nuova. Per configurare una connessione esistente, completa i seguenti passaggi nella pagina Editor attività connettori.

   La seguente immagine mostra un layout di esempio della pagina Editor attività connettori.

1. Nella sezione Seleziona connessione, seleziona la regione della connessione.
2. Scegli una connessione esistente dall'elenco delle connessioni disponibili nella regione selezionata.
3. Fai clic su Avanti.
4. Dall'elenco Tipo, seleziona Entità o Azioni.
   • Se selezioni Entità, l'elenco delle entità supportate per la connessione viene visualizzato nella sezione Imposta entità/azioni. Seleziona un'entità seguita dall'operazione che vuoi eseguire su quell'entità.
   • Se selezioni Azioni, l'elenco delle azioni supportate per la connessione viene visualizzato nella colonna Imposta entità/azioni. Seleziona un'azione per la connessione.
   Le entità e le azioni supportate dipendono dal tipo di connettore. Per l'elenco di tutti i connettori supportati per Application Integration, consulta Riferimento ai connettori. Per visualizzare le azioni e le entità supportate per un connettore, consulta la documentazione specifica del connettore.

   Se il connettore supporta query SQL personalizzate, puoi selezionare l'opzione Esegui query personalizzata dall'elenco Azioni. Per informazioni su come aggiungere una query SQL personalizzata per il connettore, consulta Azione: esegui query SQL personalizzata.

   Nota: non tutti i tipi di connessione supportano le entità o le azioni. Se un tipo di connessione non supporta azioni o entità, gli elenchi Entità e Azioni corrispondenti saranno vuoti. Per saperne di più su entità e azioni, vedi Entità, operazioni e azioni.
5. Fai clic su Fine per completare la configurazione della connessione e chiudere il riquadro.

Configurare le variabili di input e output dell'attività

Il riquadro di configurazione dell'attività Connettori mostra le variabili Input attività e Output attività che vengono generate automaticamente in base all'entità e all'operazione o all'azione selezionate nella finestra di dialogo Configura attività connettore. Queste variabili sono configurabili e accessibili come input per l'attività corrente o come output per le attività successive o per le condizioni nell'integrazione corrente.

Per configurare le variabili Input attività o Output attività, fai clic sulla variabile corrispondente per aprire il riquadro Configura variabile ed esegui i seguenti passaggi:

1. Inserisci il valore della variabile nel campo Valore predefinito.
2. (Facoltativo) Seleziona Utilizza come input per l'integrazione o Utilizza come output per l'integrazione.
3. Fai clic su Salva.

Per ulteriori informazioni sui parametri di input e output dell'attività Connettori, vedi Operazioni sulle entità.

Configura l'override dell'autenticazione

Per consentire alla connessione di accettare dinamicamente diverse autenticazioni di backend durante l'esecuzione, assicurati di aver selezionato l'opzione Attiva override autenticazione per la connessione in Integration Connectors.

Per configurare l'override dell'autenticazione:

1. Fai clic sull'elemento dell'attività dei connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connettori.
2. Espandi la sezione Input attività. Il campo Credenziali utente finale è impostato su una variabile dynamicAuthConfig.

   

   Quindi:

   1. Fai clic sulla variabile dynamicAuthConfig. Viene visualizzato il riquadro Modifica variabile.

      Per ignorare l'autenticazione, devi fornire i valori di autenticazione quando testi l'integrazione.

      

      Per farlo, segui questi passaggi:

      1. Dall'elenco Tipo di variabile, seleziona Input per l'integrazione.
      2. In Opzioni schema JSON, puoi verificare il tipo di autenticazione configurato per la connessione. Utilizza questo schema per ignorare il valore di autenticazione quando testi l'integrazione.

         

   In alternativa, puoi trasmettere l'autenticazione come intestazione HTTP selezionando la casella di controllo Usa intestazione HTTPS per la configurazione dell'autenticazione nella sezione Input attività del riquadro di configurazione dell'attività Connettori.

   

Operazioni e azioni delle entità

Puoi eseguire operazioni CRUD (Create, Read, Update, Delete) sulle entità di un connettore. Ciascuna di queste operazioni sull'entità ha un insieme diverso di parametri di input e output. La tabella seguente elenca i parametri di input e output delle varie operazioni sulle entità.

Nome operazione	Parametri di input	Parametri di output
Elenco	listEntitiesPageSize listEntitiesPageToken listEntitiesSortByColumns filterClause	connectorOutputPayload listEntitiesNextPageToken
Ottieni	entityId	connectorOutputPayload
	Nota:puoi utilizzare l'operazione Get solo per recuperare un singolo record da una tabella con una chiave primaria. In alternativa, puoi utilizzare l'operazione List con una filterClause.
Crea	connectorInputPayload	connectorOutputPayload
Aggiorna	connectorInputPayload entityId filterClause	connectorOutputPayload
Elimina	entityId filterClause	N/D

Parametri di input

La tabella seguente descrive i parametri di input per le varie operazioni sulle entità.

Nome parametro	Tipo di dati	Descrizione
entityId	Stringa	Un identificatore univoco della riga a cui vuoi accedere. In genere, entityId è un valore della chiave primaria di una tabella o di un set di dati. Se specifichi un valore per entityId e la tabella o il set di dati non ha una colonna della chiave primaria, l'integrazione segnala un errore di runtime e l'attività Connettori non riesce. Ad esempio, per ottenere una riga specifica da una tabella MySQL, entityId è il valore della chiave primaria nella tabella. Nota:entityId non è obbligatorio per BigQuery. Questo campo è vuoto quando una tabella BigQuery non ha una chiave primaria.
connectorInputPayload	JSON	I dati effettivi da aggiungere o aggiornare in un'entità. Il seguente esempio mostra lo snippet JSON dei dati di una riga da aggiungere a una tabella: { "employee_first_name": "John", "employee_emailID": "[e-mail]" } In questo esempio, employee_first_name e employee_emailID sono i nomi delle colonne con i valori corrispondenti John e [e-mail].
filterClause	Stringa	Limita il risultato delle operazioni in base a una condizione. Per saperne di più sull'aggiunta di una clausola di filtro, vedi Aggiungere un filtro per un'operazione.
listEntitiesPageSize	Numero intero	Specifica il numero di risultati da restituire in una pagina. Una pagina è un raggruppamento logico dei record in un insieme di risultati. Il concetto di pagina è utile quando prevedi un numero elevato di record nel set di risultati. Se il set di risultati è di grandi dimensioni, l'attività Connettori potrebbe non riuscire, in quanto esiste un limite alle dimensioni dei dati che l'attività Connettori può elaborare. Suddividendo il set di risultati in blocchi più piccoli, puoi evitare questo problema. Ad esempio, se prevedi 1000 record nel set di risultati, puoi impostare listEntitiesPageSize su 100. Pertanto, quando l'attività Connettori viene eseguita per la prima volta, restituisce i primi 100 record, i successivi 100 record nella seconda esecuzione e così via. Importante: La dimensione predefinita della pagina è 25 e il numero massimo di pagine supportate dall'attività è 50.000. A meno che la tabella o il set di dati non abbia una chiave primaria, devi impostare il parametro listEntitiesSortByColumns per utilizzare listEntitiesPageToken. Utilizza il parametro listEntitiesPageSize insieme al parametro listEntitiesPageToken per navigare tra le pagine.
listEntitiesPageToken	Stringa	Un identificatore di pagina (token) che ti consente di accedere a una pagina specifica. Puoi ottenere il valore di un token di pagina dal parametro di output listEntitiesNextPageToken. Poiché ogni pagina ha un token univoco, puoi accedere a qualsiasi pagina nel set di risultati. Per comprendere l'utilizzo di questo parametro, leggi anche la descrizione del parametro di output listEntitiesNextPageToken.
listEntitiesSortByColumns	Array di stringhe	Nome della colonna in base a cui vuoi ordinare il set di risultati. Nota: puoi ordinare il set di risultati solo in base a una colonna.

Parametri di output

La tabella seguente descrive i parametri di output per le varie operazioni sulle entità.

Nome parametro	Tipo di dati	Descrizione
connectorOutputPayload	JSON	L'output di un'operazione in formato JSON.
listEntitiesNextPageToken	Stringa	Un identificatore generato dal sistema per una pagina. Puoi considerare il token come un puntatore con cui puoi accedere a una pagina specifica del set di risultati. Se hai suddiviso il set di risultati in più pagine impostando il parametro listEntitiesPageSize, hai bisogno di un meccanismo per navigare tra le pagine. Il parametro di output listEntitiesNextPageToken ti consente di farlo. Ogni volta che viene eseguita l'attività Connettori, il sistema genera un token per la pagina successiva e imposta il valore di listEntitiesNextPageToken sul token appena generato. Puoi quindi utilizzare questo token per accedere alla pagina successiva nel set di risultati. Per accedere alla pagina successiva, devi impostare il parametro di input listEntitiesPageToken sul valore del token della pagina successiva. Ad esempio, supponiamo di aver impostato il parametro listEntitiesPageSize su 2 e che, quando l'attività Connettori viene eseguita per la prima volta, listEntitiesNextPageToken sia impostato sul valore del token ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Puoi quindi impostare il parametro di input listEntitiesPageToken su questo valore del token per recuperare la pagina successiva nell'esecuzione successiva dell'attività Connettori. Se il set di risultati ha un numero elevato di pagine, puoi utilizzare l'attività Ciclo While per ottenere la pagina successiva e utilizzare l'attività Mappatura dei dati per assegnare automaticamente i valori dei token di pagina al parametro di input listEntitiesPageToken dopo ogni esecuzione. Mappa listEntitiesNextPageToken dall'ultima iterazione del ciclo a listEntitiesPageToken in LIST Operation dell'attività Connettori dell'iterazione del ciclo corrente. L'attività Durante il loop termina quando listEntitiesNextPageToken è NULL, il che implica che non ci sono altre pagine.

Clausola di filtro per le operazioni sulle entità

Puoi limitare i record elaborati dall'attività Connettori utilizzando la variabile Clausola di filtro disponibile come Input attività. Ad esempio, in caso di operazione di eliminazione, puoi aggiungere una clausola di filtro per eliminare i record con un determinato orderId.

La clausola di filtro può essere applicata solo per le seguenti operazioni sulle entità:

• Elenco
• Elimina
• Aggiorna

Quando selezioni una di queste operazioni, la sezione Input attività dell'attività Connettori mostra automaticamente il campo Clausola di filtro.

Aggiungere una clausola di filtro

Per aggiungere una clausola di filtro:

1. Fai clic sull'elemento attività Connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connettori.
2. Espandi la sezione Input attività e fai clic sulla variabile stringa filterClause(Connectors).

   Viene visualizzata la finestra di dialogo Configura variabile.

3. Inserisci la clausola di filtro (seguendo la sintassi della clausola) nel campo Valore predefinito.
4. Fai clic su Salva.

Sintassi ed esempi delle clausole di filtro

Una clausola di filtro ha il seguente formato:

FIELD_NAME CONDITION FILTER_VALUE

Esempi

• OwnerId = '0053t000007941XAAQ'

• PoNumber < 2345

• OrderNumber = 00110 AND StatusCode = 'Draft'

• TotalAmount > 2500

• ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

Importante: nella clausola del filtro, specifica i valori stringa tra virgolette singole ( ' ) o doppie ( " ) a seconda del database che stai utilizzando. Ad esempio, MySQL accetta sia le virgolette singole che quelle doppie, mentre BigQuery accetta solo le virgolette singole.

Utilizzo di variabili nella clausola di filtro

Non puoi utilizzare direttamente una variabile di integrazione in una clausola di filtro. Se vuoi utilizzare una variabile di integrazione, devi prima configurare un'attività di mappatura dei dati per creare una mappatura tra la variabile di integrazione e la clausola di filtro.

La seguente tabella mostra un esempio di mappatura tra una variabile di integrazione e la variabile filterClause(Connectors):

Input	Output
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(')	filterClause(Connectors)

Dove PRIMARY_KEY_ID = ' viene inserito come Valore nella riga di input.

---

Azione: esegui query SQL personalizzata

Per creare una query personalizzata:

1. Segui le istruzioni dettagliate per aggiungere un'attività di connettori.
2. Quando configuri l'attività del connettore, seleziona Azioni nel tipo di azione che vuoi eseguire.
3. Nell'elenco Azione, seleziona Esegui query personalizzata, quindi fai clic su Fine.

   

4. Espandi la sezione Input attività e segui questi passaggi:
   1. Nel campo Timeout dopo, inserisci il numero di secondi di attesa prima dell'esecuzione della query.

      Valore predefinito: 180 secondi.

   2. Nel campo Numero massimo di righe, inserisci il numero massimo di righe da restituire dal database.

      Valore predefinito: 25.

   3. Per aggiornare la query personalizzata, fai clic su Modifica script personalizzato. Si apre la finestra di dialogo Editor di script.

      

   4. Nella finestra di dialogo Editor script, inserisci la query SQL e fai clic su Salva.

      Puoi utilizzare un punto interrogativo (?) in un'istruzione SQL per rappresentare un singolo parametro che deve essere specificato nell'elenco parametri di ricerca. Ad esempio, la seguente query SQL seleziona tutte le righe della tabella Employees che corrispondono ai valori specificati per la colonna LastName:

      SELECT * FROM Employees where LastName=?

      Nota:sono supportate le istruzioni DML (Data Manipulation Language) e DDL (Data Definition Language).
   5. Se hai utilizzato punti interrogativi nella query SQL, devi aggiungere il parametro facendo clic su + Aggiungi nome parametro per ogni punto interrogativo. Durante l'esecuzione dell'integrazione, questi parametri sostituiscono in sequenza i punti interrogativi (?) nella query SQL. Ad esempio, se hai aggiunto tre punti interrogativi (?), devi aggiungere tre parametri in ordine di sequenza.

      

      Per aggiungere parametri di ricerca:

      1. Nell'elenco Tipo, seleziona il tipo di dati del parametro.
      2. Nel campo Valore, inserisci il valore del parametro.
      3. Per aggiungere più parametri, fai clic su + Aggiungi parametro di query.

   L'azione Esegui query personalizzata non supporta le variabili array.

Aggiornamento dello schema

Tutte le entità e le azioni avranno uno schema associato. Ad esempio, uno schema di azione avrà i dettagli dei parametri, ad esempio i nomi dei parametri e il tipo di dati corrispondente. Lo schema (metadati) per entità e azioni viene recuperato dalla connessione in fase di runtime dal backend. Se vengono apportati aggiornamenti allo schema, questi non verranno riflessi automaticamente nelle connessioni esistenti; devi aggiornare manualmente lo schema.

Per visualizzare lo schema aggiornato nelle attività del connettore esistenti:
1. In Integration Connectors, apri la pagina Dettagli connessione della connessione, poi fai clic su Aggiorna schema connessione.
2. In Application Integration, devi riconfigurare l'attività del connettore esistente per la stessa connessione.

Creazione di connessioni inline

Puoi utilizzare l'attività Connettori per creare direttamente una nuova connessione in Integration Connectors.

Prima di iniziare

• Aggiungere un'attività del connettore

Crea nuova connessione

Per creare una nuova connessione da Application Integration, segui questi passaggi:

1. Fai clic sull'elemento attività Connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connettori.
2. Fai clic su Configura connettore.

   Viene visualizzata la pagina Editor attività connettori.

3. Ignora il campo Regione.
4. Fai clic su Connessione e seleziona l'opzione Crea connessione dal menu a discesa.
5. Completa i seguenti passaggi nel riquadro Crea connessione:
   Nota:le seguenti istruzioni sono i passaggi generici per creare una connessione. Sebbene la maggior parte dei passaggi rimanga invariata per tutti i tipi di connessione, alcuni passaggi o dettagli aggiuntivi relativi all'autenticazione potrebbero variare.

   Ti consigliamo di consultare anche la documentazione relativa al tipo di connessione in Integration Connectors.

   1. Nel passaggio Posizione, scegli la posizione della connessione.
      1. Fai clic su Regione e seleziona una località dall'elenco a discesa.
      2. Fai clic su Avanti.
   2. Nel passaggio Dettagli connessione, fornisci i dettagli della connessione:
      1. Connettore:seleziona il tipo di connettore da creare dall'elenco a discesa. Per informazioni sull'elenco dei connettori supportati, vedi Tutti i connettori di integrazione.
      2. Versione del connettore:scegli una versione disponibile del tipo di connettore selezionato dall'elenco a discesa.
      3. Nome connessione:inserisci un nome per l'istanza di connessione.
         Nota:i nomi delle connessioni devono soddisfare i seguenti criteri:

         • I nomi delle connessioni possono contenere lettere, numeri o trattini.
         • Le lettere devono essere minuscole.
         • I nomi delle connessioni devono iniziare con una lettera e terminare con una lettera o un numero.
         • I nomi delle connessioni non possono superare i 63 caratteri.
      4. (Facoltativo) Inserisci una Descrizione per l'istanza di connessione.
      5. (Facoltativo) Seleziona Abilita Cloud Logging per archiviare i dati di log dell'istanza di connessione.
      6. Service Account: seleziona un account di servizio con i ruoli richiesti.
      7. (Facoltativo) Fai clic su Impostazioni avanzate per configurare le impostazioni del nodo di connessione.

         Per saperne di più, consulta la documentazione relativa alla connessione in Integration Connectors.

      8. (Facoltativo) Fai clic su + AGGIUNGI ETICHETTA per aggiungere un'etichetta alla connessione sotto forma di coppia chiave/valore.
      9. Fai clic su Avanti.
   3. Nel passaggio Autenticazione, fornisci i dettagli di autenticazione per la connessione.
      1. I metodi di autenticazione compilati durante questo passaggio si basano sul tipo di connessione che viene creata.

         I diversi tipi di connessione utilizzano metodi di autenticazione diversi. Per saperne di più, consulta la sezione Configurare l'autenticazione della documentazione relativa alla connessione in Integration Connectors.

      2. Fai clic su Avanti.
   4. Rivedi: rivedi i dettagli di connessione e autenticazione.
   5. Fai clic su Crea.

---

Best practice

• Per informazioni sui limiti di utilizzo che si applicano all'attività Connettori, vedi Limiti di utilizzo.
• Per informazioni su come risolvere i problemi relativi a un'attività Connettori non riuscita, vedi Utilizzare i log per risolvere i problemi e tracciare gli errori dei connettori.

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.

Prezzi

Il trigger Cloud Pub/Sub e il trigger Salesforce non richiedono la creazione di un connettore. Tuttavia, se utilizzi l'attività Connettori per connetterti a Pub/Sub o Salesforce, ti viene addebitato l'utilizzo del connettore. Per informazioni sui prezzi, consulta Prezzi di Application Integration.

Quote e limiti

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

Passaggi successivi

• Scopri di più su tutte le attività e tutti gli attivatori.
• Scopri come testare e pubblicare un'integrazione.
• Scopri di più sulla gestione degli errori.
• Scopri di più sui log di esecuzione dell'integrazione.