Adempimento delle richieste API

---

Questo tutorial descrive un caso d'uso su come utilizzare l'integrazione delle applicazioni per instradare e recuperare informazioni per una richiesta API di Ingress.

Panoramica

In questo tutorial, creerai un'integrazione con un trigger API che riceve richieste API per il recupero delle informazioni sui clienti. A seconda della posizione della richiesta dell'API, l'integrazione recupera i dettagli del cliente da un database MySQL o da un database Oracle.

Obiettivi

Questo tutorial mostra come completare le seguenti attività nell'integrazione:

• Aggiungi un trigger API.
• Aggiungi e configura le attività dei connettori per le connessioni MySQL e Oracle.
• Aggiungi e configura le attività di mappatura dei dati per estrarre e mappare il payload dell'API.

Costi

In questo tutorial utilizzi i seguenti componenti fatturabili di Google Cloud:

• Application Integration
• Integration Connectors
• Secret Manager

Le istruzioni in questo tutorial sono progettate per mantenere l'utilizzo delle risorse entro i limiti del livello Sempre gratis di Google Cloud.

Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.

Prima di iniziare

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

   4. Click Create and continue.

   5. Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

      To grant a role, find the Select a role list, then select the role.

      To grant additional roles, click Add another role and add each additional role.

      Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
   6. Click Continue.

   7. Click Done to finish creating the service account.

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

   4. Click Create and continue.

   5. Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

      To grant a role, find the Select a role list, then select the role.

      To grant additional roles, click Add another role and add each additional role.

      Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
   6. Click Continue.

   7. Click Done to finish creating the service account.

Nota: tutte le altre API Google Cloud richieste, come l'API Application Integration, l'API Secret Manager e l'API Connectors, vengono attivate durante la configurazione di Application Integration. Per maggiori dettagli, vedi Configurare l'integrazione delle applicazioni.

prepara l'ambiente

Configurare un database MySQL

Connettiti al server MySQL e crea un database e una tabella da utilizzare in questo tutorial. Questo tutorial utilizza un database che contiene una tabella denominata Customers con le seguenti righe:

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Alex          | [e-mail]   | New York         |
  |           2 | Dana          | [e-mail]   | Seattle          |
  +-------------+---------------+--------------------+------------------+
  

Per informazioni su come creare e utilizzare un database MySQL, consulta la documentazione di MySQL.

Configurare un database Oracle

Connettiti al tuo database Oracle e crea una tabella da utilizzare in questo tutorial. Questo tutorial utilizza un database che contiene una tabella SQL denominata Customers con le seguenti righe:

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Amal          | [e-mail]   | Delhi            |
  |           2 | Hao           | [e-mail]   | Beijing          |
  +-------------+---------------+--------------------+------------------+
  

Per informazioni sulla creazione e sull'utilizzo di un database Oracle, consulta la documentazione di Oracle.

Configura connessioni

Per questo tutorial, devi configurare le seguenti connessioni in Integration Connectors:

Suggerimento: ti consigliamo di creare le seguenti connessioni nella regione us-central1(lowa).

Connessione MySQL

Configura una connessione MySQL in Integration Connectors per ottenere le entità delle tabelle Customer. Per informazioni sulla configurazione di un connettore MySQL, consulta Connettore MySQL.

Connessione al database Oracle

Configura una connessione al database Oracle in Integration Connectors per ottenere le entità delle tabelle Customer. Per informazioni sulla configurazione di un connettore MySQL, consulta Connettore per database Oracle.

Crea l'integrazione

Per creare una nuova 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.
3. Fai clic su Crea integrazione e fornisci i seguenti dettagli nella pagina Crea integrazione:
   1. Nome integrazione: inserisci api_fulfilment.
   2. Descrizione: inserisci Demo integration created for tutorial.
   3. Regione: seleziona us-central1 dall'elenco delle regioni supportate.
   4. Fai clic su Crea per aprire l'editor di integrazione.

Configura l'trigger di integrazione

Dopo aver creato l'integrazione, puoi aggiungere e configurare un attivatore di integrazione che la richiami per un evento identificato.

Per questo tutorial, viene utilizzato un trigger API per richiamare l'integrazione per ogni nuova richiesta API. Per aggiungere e configurare un trigger API nell'integrazione di api_fulfilment:

1. Nell'editor dell'integrazione, fai clic su Attivatori per visualizzare un elenco degli attivatori disponibili.
2. Fai clic e posiziona l'elemento API trigger nell'editor di integrazione.

   L'integrazione delle applicazioni compila automaticamente l'etichetta, il nome e l'ID dell'attivatore. L'ID trigger è un ID generato automaticamente nel formato api_trigger/TRIGGER_NAME e viene utilizzato nella richiesta API.

Non è necessaria alcuna ulteriore configurazione per questo attivatore.

Creare variabili di integrazione

Le variabili di integrazione sono simili a quelle utilizzate in un linguaggio di programmazione. I dati nelle variabili possono essere letti e scritti durante l'esecuzione dell'integrazione. Per creare le variabili richieste per questo tutorial:

1. Fai clic su (Attiva/disattiva riquadro) nella barra di navigazione del designer per visualizzare il riquadro Variabili.
2. Fai clic su + Crea e crea le seguenti variabili di integrazione:

   Nome variabile	Tipo di dati	Tipo di variabile
   location	STRING	Input all'integrazione
   customer_id	STRING	Input all'integrazione
   customer_record	JSON	Output dell'integrazione

Recuperare i dati dei clienti dal database MySQL

Se la richiesta dell'API di importazione proviene dalla località US, svolgi i seguenti passaggi per recuperare i dati dei clienti dal database MySQL.

Connettiti al database MySQL

Per aggiungere e configurare un'attività Connettori per recuperare i dettagli dei clienti dalla tabella Clienti di MySQL:

1. Nell'editor di integrazione, fai clic su Attività per visualizzare un elenco delle attività disponibili.
2. Fai clic e posiziona l'elemento Connettori nell'editor di integrazione.
3. Seleziona l'elemento dell'attività Connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connessioni.
4. Fai clic su e rinomina l'etichetta Connettori in Fetch MySQL Data.
5. Fai clic su Configura connettore.
6. Nella pagina Editor attività dei connettori:
   1. In Seleziona connessione, scegli la regione us-central1.
   2. Seleziona la connessione Salesforce dall'elenco delle connessioni disponibili.
   3. Fai clic su Avanti.
   4. In Tipo, scegli Entità.
   5. In Imposta entità/azioni, seleziona Clienti dall'elenco delle entità disponibili e poi Ottieni come Operazione.
   6. Fai clic su Fine per completare la configurazione della connessione e chiudere il riquadro.

Mappa l'ID cliente al connettore MySQL

Per mappare l'ID cliente al connettore MySQL viene utilizzata un'attività di mappatura dei dati. Per aggiungere e configurare la mappatura dei dati nell'integrazione:

1. Nell'editor di integrazione, fai clic su Attività per visualizzare un elenco delle attività disponibili.
2. Fai clic e posiziona l'elemento Mappatura dei dati nell'editor di integrazione.
3. Seleziona l'elemento Mappatura dati nel designer per visualizzare il riquadro di configurazione dell'attività.
4. Fai clic su e rinomina l'attività Mappatura dei dati in Map to MySQL.
5. Fai clic su Apri editor di mappatura dei dati.

   L'editor di mappatura dei dati ti consente di mappare le variabili di input alle variabili di output desiderate utilizzando le funzioni di trasformazione disponibili. L'output è quindi disponibile come variabile per qualsiasi altra attività o trigger di integrazione. Per ulteriori dettagli sulle variabili di mappatura, vedi Aggiungere una mappatura.

6. Mappa la variabile di integrazione dell'trigger -customer_id- al connettore autogenerato -entityId(Fetch MySQL Data)-.

   Al termine della mappatura, chiudi il riquadro. Eventuali modifiche verranno salvate automaticamente.

7. Aggiungi una connessione di elaborazione dall'attività Mappa in MySQL al connettore Recupero dati MySQL.

Recuperare i dettagli del cliente MySQL

Per recuperare i dettagli del cliente dal connettore MySQL:

1. Nell'editor di integrazione, fai clic su Attività per visualizzare un elenco delle attività disponibili.
2. Fai clic e posiziona l'elemento Mappatura dei dati nell'editor di integrazione.
3. Fai clic sull'elemento Mappatura dei dati nel designer per visualizzare il riquadro di configurazione dell'attività.
4. Fai clic su e rinomina l'attività Mappatura dei dati in Get MySQL data.
5. Fai clic su Apri editor di mappatura dei dati.
6. Mappa la variabile di output MySQL - connectorOutputPayload (Fetch MySQL Data) alla variabile di integrazione customer_record.

   Al termine della mappatura, chiudi il riquadro. Eventuali modifiche verranno salvate automaticamente.

7. Aggiungi una connessione di elaborazione dal connettore Recupero dati MySQL all'attività Recupero dati MySQL.

Recuperare i dati dei clienti dal database Oracle

Se la richiesta dell'API di importazione proviene dalla località APAC, procedi nel seguente modo per recuperare i dati dei clienti dal database Oracle.

Connettiti al database Oracle

Per aggiungere e configurare un'attività Connectors per recuperare i dettagli dei clienti dalla tabella Customers di Oracle:

1. Nell'editor di integrazione, fai clic su Attività per visualizzare un elenco delle attività disponibili.
2. Fai clic e posiziona l'elemento Connettori nell'editor di integrazione.
3. Seleziona l'elemento dell'attività Connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connessioni.
4. Fai clic su e rinomina l'etichetta Connettori in Fetch Oracle Data.
5. Fai clic su Configura connettore.
6. Nella pagina Editor attività dei connettori:
   1. In Seleziona connessione, scegli la regione us-central1.
   2. Seleziona la connessione Salesforce dall'elenco delle connessioni disponibili.
   3. Fai clic su Avanti.
   4. In Tipo, scegli Entità.
   5. In Imposta entità/azioni, seleziona Clienti dall'elenco delle entità disponibili e poi Ottieni come Operazione.
   6. Fai clic su Fine per completare la configurazione della connessione e chiudere il riquadro.

Mappa l'ID cliente al connettore Oracle

Per aggiungere e configurare la mappatura dei dati nell'integrazione:

1. Nell'editor di integrazione, fai clic su Attività per visualizzare un elenco delle attività disponibili.
2. Fai clic e posiziona l'elemento Mappatura dei dati nell'editor di integrazione.
3. Seleziona l'elemento Mappatura dati nel designer per visualizzare il riquadro di configurazione dell'attività.
4. Fai clic su e rinomina l'attività Mappatura dei dati in Map to Oracle.
5. Fai clic su Apri editor di mappatura dei dati.
6. Mappa la variabile di integrazione dell'trigger -customer_id- al connettore autogenerato -entityId(Fetch Oracle Data)-.

   Al termine della mappatura, chiudi il riquadro. Eventuali modifiche verranno salvate automaticamente.

7. Aggiungi una connessione di bordo dall'attività Mappa in Oracle al connettore Recupero dati Oracle.

Recuperare i dettagli del cliente Oracle

Per recuperare i dettagli del cliente dal connettore Oracle:

1. Nell'editor di integrazione, fai clic su Attività per visualizzare un elenco delle attività disponibili.
2. Fai clic e posiziona l'elemento Mappatura dei dati nell'editor di integrazione.
3. Fai clic sull'elemento Mappatura dei dati nel designer per visualizzare il riquadro di configurazione dell'attività.
4. Fai clic su e rinomina l'attività Mappatura dei dati in Get Oracle data.
5. Fai clic su Apri editor di mappatura dei dati.
6. Mappa la variabile di output Oracle -connectorOutputPayload (Fetch Oracle Data)- alla variabile di integrazione customer_record.

   Al termine della mappatura, chiudi il riquadro. Eventuali modifiche verranno salvate automaticamente.

7. Aggiungi una connessione di flusso dal connettore Recupero dati Oracle all'attività Recupero dati Oracle.

Aggiungi condizione di confine

Una condizione di bordo consente di specificare le condizioni che devono essere soddisfatte affinché il controllo di un'integrazione venga passato all'attività collegata dal bordo. Ora che hai aggiunto e configurato le attività richieste, puoi aggiungere una condizione di bordo per definire il flusso dell'integrazione.

La seguente condizione di confine controlla il flusso dell'integrazione in base alla variabile di integrazione location:

1. Aggiungi una connessione di bordo dall'attivatore API all'attività Mappa in MySQL con la seguente condizione di bordo:

     $location$ = "US"

2. Aggiungi un'altra connessione di bordo dall'attivatore API all'attività Map to Oracle con la seguente condizione di bordo:

     $location$ = "APAC"

Flusso di integrazione di esempio

La figura seguente mostra un layout di esempio dell'integrazione creata utilizzando questo tutorial.

Pubblicare l'integrazione

Per pubblicare l'integrazione, fai clic su Pubblica nella barra degli strumenti dell'Editor integrazioni.

Una volta completata la pubblicazione dell'integrazione, puoi visualizzare e controllare i log di esecuzione dell'integrazione pubblicata. Per visualizzare i log, fai clic su Visualizza i log di esecuzione per questa integrazione. Viene visualizzata la pagina Log di esecuzione.

Testa l'integrazione

Testare l'integrazione dall'editor integrazioni

Per testare l'integrazione dall'editor di integrazione, segui questi passaggi:

1. Fai clic su Test nella barra degli strumenti dell'Editor integrazioni.

   Viene visualizzato il riquadro Testa integrazione.

2. Ti viene chiesto di inserire i valori di test per le variabili di input dell'integrazione. Ai fini di questo test, svolgi i seguenti passaggi:
   • customer_id: inserisci 1.
   • location: inserisci APAC.
3. Fai clic su Test Integration (Testa integrazione).

L'integrazione viene eseguita correttamente e viene visualizzato il seguente valore cliente:

{ 
  "CUSTOMER_ID": 1,
  "CUSTOMER_NAME": "Amal"
  "CUSTOMER_EMAILID": "[e-mail] "
  "CUSTOMER_CITY": "Delhi"
}

Per ulteriori informazioni sui test, consulta Testare e pubblicare le integrazioni.

Eseguire il test utilizzando una chiamata API REST

Ora che l'integrazione è pubblicata ed è in esecuzione, puoi invocarla utilizzando la seguente chiamata REST POST:

URL:

https://integrations.googleapis.com/v1/projects/project-name/locations/-/integrations/api_fulfilment:execute 

Corpo della richiesta:

{"trigger_id":"api_trigger/api_fulfilment_API_1"}

Esempio: effettua una richiesta API con input personalizzati

Nota: il seguente esempio utilizza curl, che in genere è preinstallato per i sistemi operativi Linux e macOS. Se non hai curl, puoi scaricarlo dalla pagina delle release e dei download di curl.

curl -v -X POST -H "Content-Type: application/json" 'https://integrations.googleapis.com/v1/projects/connectors-ip-test/locations/us-central1/integrations/api-fulfillment-integration:execute' -H "Authorization: Bearer $(gcloud auth AUTH_PROFILE)" -d  '{ "triggerId": "api_trigger/api-fulfillment-integration_API_1", "inputParameters": { "customer_id": {"string_value": 1}, "location" : {"string_value" : "US"}} }'

L'API restituisce la risposta all'esecuzione dell'integrazione contenente tutto il seguente JSON:

  { 
    "CUSTOMER_ID": 2,
    "CUSTOMER_NAME": "Dana"
    "CUSTOMER_EMAILID": "[e-mail] "
    "CUSTOMER_CITY": "Seattle"
  }
  

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, annulla la pubblicazione dell'integrazione ed elimina le connessioni create in Integration Connectors.

• Per annullare la pubblicazione di questa integrazione, fai clic su Annulla pubblicazione nella barra degli strumenti dell'Editor integrazioni. Per ulteriori informazioni, consulta Eliminare le integrazioni.
• Per informazioni su come eliminare una connessione, consulta Gestire i connettori.