Attività connettori

Annuncio: Application Integration è ora disponibile per il tuo progetto Google Cloud. Ora puoi utilizzare sia Apigee Integration che Application Integration all'interno dello stesso progetto Google Cloud. Scopri di più

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 pronti all'uso disponibili in Integration Connectors.

Per l'elenco di tutti i connettori supportati per Apigee Integration, consulta la documentazione di riferimento dei connettori.

Importante: Integration Connectors è un componente fatturabile di Google Cloud. Per informazioni sui costi e sugli addebiti per l'utilizzo di Integration Connectors, consulta Prezzi di Integration Connectors.

Prima di iniziare

• Assicurati che ti sia stato concesso il ruolo IAM Amministratore connettori (roles/connectors.admin) nel progetto Google Cloud. Per informazioni sulla concessione dei ruoli, consulta 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 account di servizio gestito dall'utente all'integrazione. Se per l'integrazione non è configurato un account di servizio gestito dall'utente, per l'autenticazione viene utilizzato per impostazione predefinita l'account di servizio predefinito ([e-mail]).
• Assicurati che il tuo account di servizio disponga del ruolo IAM richiesto. Per informazioni sulla concessione dei ruoli a un account di servizio, vedi Gestire l'accesso agli account di servizio.

Aggiungi un'attività Connettori

Per aggiungere l'attività Connettori nell'integrazione:

1. Nell'interfaccia utente di Apigee, seleziona la tua organizzazione Apigee.
2. Fai clic su Sviluppa > Integrazioni.
3. Seleziona un'integrazione esistente o creane una nuova facendo clic su Crea integrazione.

   Se stai creando una nuova integrazione:

   1. Inserisci un nome e una descrizione nella finestra di dialogo Crea integrazione.
   2. Seleziona una regione per l'integrazione dall'elenco delle regioni supportate.
   3. Fai clic su Crea.

   In questo modo viene aperta l'integrazione nel designer dell'integrazione.

4. Nella barra di navigazione del designer dell'integrazione, fai clic su +Aggiungi un'attività/un trigger > Tasks per visualizzare l'elenco delle attività disponibili.
5. Fai clic sull'elemento Connettori e posizionalo nell'editor di integrazione.

Configura l'attività Connettori

Per configurare un'attività Connettori:

Nota: i dettagli di configurazione, come l'autenticazione, variano in base al tipo di connessione.

1. Fai clic sull'elemento dell'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:
1. In Seleziona connettori, scegli l'area geografica della connessione.
2. Scegli una connessione esistente dall'elenco di connessioni disponibili nella regione selezionata.
3. Tocca Avanti.
4. Nell'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 questa 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 si basano sul tipo di connettore. Per l'elenco di tutti i connettori supportati per Apigee Integration, consulta la documentazione di riferimento dei connettori. Per visualizzare le azioni e le entità supportate per un connettore, consulta la documentazione specifica del connettore.

   Se il connettore supporta una query SQL personalizzata, puoi selezionare l'opzione Esegui query personalizzata dall'elenco Azioni. Ad esempio, per scoprire come aggiungere una query SQL personalizzata per un connettore BigQuery, consulta Eseguire una query SQL personalizzata.

   Per saperne di più su entità e azioni, consulta Entità, operazioni e azioni.

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

L'immagine seguente mostra un layout di esempio della pagina Connectors Task Editor (Editor attività connettori).

Configura variabili di input e output delle attività

Il riquadro di configurazione dell'attività Connettori mostra le variabili di Input attività e Output attività generate automaticamente in base alle voci Entità e operazione o Azione selezionate nella finestra di dialogo Configura attività del connettore. Queste variabili sono configurabili e accessibili come input per l'attività corrente o come output per le attività successive oppure come condizionali nell'integrazione corrente.

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

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

Per saperne di più sui parametri di input e di output dell'attività Connettori, consulta Operazioni sulle entità.

Operazioni sulle entità

Puoi eseguire operazioni CRUD (creazione, lettura, aggiornamento, eliminazione) sulle entità di un connettore. Ognuna di queste operazioni delle entità ha un insieme diverso di parametri di input e di output. Nella tabella seguente sono elencati i parametri di input e di output delle varie operazioni delle entità.

Nome operazione	Parametri di input	Parametri di output
Elenco	listEntitiesPageSize listEntitiesPageToken listEntitiesSortByColumns filterClause	connectorOutputPayload listEntitiesNextPageToken
Get	entityId	connectorOutputPayload
	Nota: puoi utilizzare l'operazione Get solo per recuperare un singolo record da una tabella che ha una chiave primaria. In alternativa, puoi utilizzare l'operazione List con un 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 delle entità.

Nome parametro	Tipo di dati	Descrizione
entityId	Stringa	Un identificatore univoco della riga a cui vuoi accedere. Normalmente, entityId è un valore di 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 di chiave primaria, l'integrazione segnala un errore di runtime e l'attività Connettori non va a buon fine. 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 se una tabella BigQuery non ha una chiave primaria.
connectorInputPayload	JSON	I dati effettivi da aggiungere o aggiornare in un'entità. L'esempio seguente mostra lo snippet JSON di dati di una riga da aggiungere in 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, consulta Aggiungere un filtro per un'operazione.
listEntitiesPageSize	Numero intero	Specifica il numero di risultati che devono essere restituiti in una pagina. Una pagina è un raggruppamento logico di record in un set 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, poiché esiste un limite alle dimensioni dei dati che l'attività Connettori può elaborare. Per evitare questo problema, suddividendo il risultato impostato in blocchi più piccoli puoi evitare questo problema. Ad esempio, se prevedi 1000 record nel set di risultati, puoi impostare listEntitiesPageSize su 100. Quindi, 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: Le dimensioni predefinite delle pagine sono 25 e il numero massimo di pagine supportate dall'attività è 200. A meno che la tua tabella o il tuo set di dati non abbia una chiave primaria, devi impostare il parametro listEntitiesSortByColumns per utilizzare listEntitiesPageToken. Utilizza l'unione del parametro listEntitiesPageSize con il parametro listEntitiesPageToken per navigare nelle pagine.
listEntitiesPageToken	Stringa	Un identificatore di pagina (token) che 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, hai la flessibilità di accedere a qualsiasi pagina vuoi 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 al quale vuoi ordinare il set di risultati. Nota: puoi ordinare il risultato impostato su una sola colonna.

Parametri di output

La tabella seguente descrive i parametri di output per le varie operazioni delle 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 tramite il quale puoi accedere a una determinata pagina del set di risultati. Se hai suddiviso il set di risultati in più pagine impostando il parametro listEntitiesPageSize, devi avere un meccanismo per navigare tra le pagine. Il parametro di output listEntitiesNextPageToken consente di fare esattamente questo. 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, quando l'attività Connettori viene eseguita per la prima volta, listEntitiesNextPageToken viene 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 considerare l'utilizzo dell'attività Per ogni loop per chiamare ripetutamente l'attività Connettori e l'attività Mappatura dei dati per assegnare automaticamente i valori token al parametro di input listEntitiesPageToken dopo ogni esecuzione.

Clausola filtro per le operazioni dell'entità

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

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

• Elenco
• Elimina
• Aggiorna

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

Aggiungi una clausola di filtro

Per aggiungere una clausola di filtro, segui questi passaggi:

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

   Viene visualizzata la finestra di dialogo Configura variabile.

3. Inserisci la clausola di filtro (in base alla clausola syntax) 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 di filtro, specifica i valori della 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 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 una mappatura di esempio 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.

---

Creazione della connessione in linea

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

Prima di iniziare

• Aggiungere un'attività Connettore

Crea nuova connessione

Per creare una nuova connessione da Apigee Integration, esegui questi passaggi:

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

   Viene visualizzata la pagina Connectors Task Editor (Editor attività connettori).

3. Salta 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 passaggi generici per creare una connessione. Anche se la maggior parte dei passaggi rimane la stessa per tutti i tipi di connessione, alcuni passaggi o dettagli aggiuntivi relativi all'autenticazione potrebbero variare.

   Ti consigliamo di visualizzare anche la documentazione relativa ai rispettivi tipi di connessione in Integration Connectors.

   1. Nel passaggio Posizione, scegli la località della connessione.
      1. Fai clic su Regione e seleziona una località dall'elenco a discesa.
      2. Tocca Avanti.
   2. Nel passaggio Dettagli connessione, fornisci i dettagli sulla connessione:
      1. Connettore: seleziona dall'elenco a discesa il tipo di connettore da creare. Per informazioni sull'elenco dei connettori supportati, consulta Tutti i connettori di integrazione.
      2. Versione 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. Account di servizio: seleziona un account di servizio con i ruoli richiesti.
      7. (Facoltativo) Fai clic su Impostazioni avanzate per configurare le impostazioni dei nodi di connessione.

         Per saperne di più, consulta la rispettiva documentazione sulle connessioni in Integration Connectors.

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

         I diversi tipi di connessione utilizzano metodi di autenticazione diversi. Per saperne di più, consulta la sezione Configura l'autenticazione della rispettiva documentazione sulle connessioni in Integration Connectors.

      2. Tocca Avanti.
   4. Verifica: controlla 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, consulta 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 dei connettori e tenere traccia degli errori.

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 per conoscere i diversi tipi di strategie di gestione degli errori, consulta Strategie di gestione degli errori.