Esecuzione della richiesta API

Questo tutorial descrive un caso d'uso su come utilizzare Application Integration per instradare e recuperare informazioni per una richiesta API in entrata.

Panoramica

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

Diagramma di evasione dell'API Diagramma di evasione dell'API

prepara l'ambiente

Configura 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          | test-01@test.com   | New York         |
  |           2 | Dana          | test-02@test.com   | Seattle          |
  +-------------+---------------+--------------------+------------------+

Per informazioni sulla creazione e sull'utilizzo di 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          | test-01@test.com   | Delhi            |
  |           2 | Hao           | test-02@test.com   | Beijing          |
  +-------------+---------------+--------------------+------------------+

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

Configura connessioni

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

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 Oracle DB
Configura una connessione al database Oracle in Integration Connectors per ottenere le entità delle tabelle Customer. Per informazioni sulla configurazione di un connettore MySQL, vedi Connettore Oracle DB.

Crea integrazione

Per creare una nuova integrazione:

  1. Nella console Google Cloud, vai alla pagina Application Integration.

    Vai ad Application Integration

  2. Fai clic su Integrazioni nel menu di navigazione a sinistra per aprire 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 il trigger di integrazione

Una volta creata l'integrazione, puoi aggiungere e configurare un trigger di integrazione che la richiama 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 api_fulfilment:

  1. Nell'editor dell'integrazione, fai clic su Attivatori per visualizzare un elenco degli attivatori disponibili.
  2. Fai clic sull'elemento API trigger e posizionalo nell'Editor integrazioni.

    L'Application Integration compila automaticamente l'etichetta, il nome e l'ID del trigger. L'ID trigger è un ID generato automaticamente nel formato api_trigger/TRIGGER_NAME e viene utilizzato nella richiesta API.

    3. Non è necessaria alcuna ulteriore configurazione per questo trigger.

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 pannello) 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 per l'integrazione
    customer_id STRING Input per l'integrazione
    customer_record JSON Output dell'integrazione

Recuperare i dati dei clienti dal database MySQL

Se la richiesta API in entrata proviene dalla località US, procedi nel seguente modo per recuperare i dati dei clienti dal database MySQL.

Connettiti al database MySQL

Esegui i seguenti passaggi per aggiungere e configurare un'attività Connettori per recuperare i dettagli dei clienti dalla tabella Customers di MySQL:

  1. Nell'editor integrazioni, fai clic su Attività per visualizzare un elenco delle attività disponibili.
  2. Fai clic sull'elemento Connettori e posizionalo nell'Editor integrazioni.
  3. Seleziona l'elemento dell'attività Connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connettori.
  4. Fai clic su e rinomina l'etichetta Connettori in Fetch MySQL Data.
  5. Fai clic su Configura connettore.
  6. Nella pagina Editor attività connettori, esegui le seguenti operazioni:
    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 Type (Tipo), scegli Entities (Entità).
    5. In Imposta entità/azioni, seleziona Clienti dall'elenco delle entità disponibili e poi seleziona 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

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

  1. Nell'editor integrazioni, fai clic su Attività per visualizzare un elenco delle attività disponibili.
  2. Fai clic sull'elemento Mappatura dei dati e posizionalo nell'Editor integrazioni.
  3. Seleziona l'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 Map to MySQL.
  5. Fai clic su Apri editor mappatura 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 del trigger —customer_id— alla variabile di input del connettore generato automaticamente —entityId(Fetch MySQL Data).

    Una volta completata la mappatura, chiudi il riquadro. Tutte le modifiche verranno salvate automaticamente.

  7. Aggiungi una connessione edge dall'attività Mappa a MySQL al connettore Recupera dati MySQL.

Recuperare i dettagli cliente MySQL

Per recuperare i dettagli del cliente dal connettore MySQL:

  1. Nell'editor integrazioni, fai clic su Attività per visualizzare un elenco delle attività disponibili.
  2. Fai clic sull'elemento Mappatura dei dati e posizionalo nell'Editor integrazioni.
  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 mappatura dati.
  6. Mappa la variabile di output MySQL—connectorOutputPayload (Fetch MySQL Data)—alla variabile di integrazione customer_record.

    Una volta completata la mappatura, chiudi il riquadro. Tutte le modifiche verranno salvate automaticamente.

  7. Aggiungi una connessione perimetrale dal connettore Recupera dati MySQL all'attività Recupera dati MySQL.

Recuperare i dati dei clienti dal database Oracle

Se la richiesta API in entrata 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à Connettori per recuperare i dettagli dei clienti dalla tabella Customers di Oracle:

  1. Nell'editor integrazioni, fai clic su Attività per visualizzare un elenco delle attività disponibili.
  2. Fai clic sull'elemento Connettori e posizionalo nell'Editor integrazioni.
  3. Seleziona l'elemento dell'attività Connettori nel designer per visualizzare il riquadro di configurazione dell'attività Connettori.
  4. Fai clic su e rinomina l'etichetta Connettori in Fetch Oracle Data.
  5. Fai clic su Configura connettore.
  6. Nella pagina Editor attività connettori, esegui le seguenti operazioni:
    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 Type (Tipo), scegli Entities (Entità).
    5. In Imposta entità/azioni, seleziona Clienti dall'elenco delle entità disponibili e poi seleziona 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 integrazioni, fai clic su Attività per visualizzare un elenco delle attività disponibili.
  2. Fai clic sull'elemento Mappatura dei dati e posizionalo nell'Editor integrazioni.
  3. Seleziona l'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 Map to Oracle.
  5. Fai clic su Apri editor mappatura dati.
  6. Mappa la variabile di integrazione del trigger —customer_id— alla variabile di input del connettore generato automaticamente —entityId(Fetch Oracle Data).

    Una volta completata la mappatura, chiudi il riquadro. Tutte le modifiche verranno salvate automaticamente.

  7. Aggiungi una connessione edge dall'attività Mappa a Oracle al connettore Recupera dati Oracle.

Recuperare i dettagli del cliente Oracle

Per recuperare i dettagli del cliente dal connettore Oracle:

  1. Nell'editor integrazioni, fai clic su Attività per visualizzare un elenco delle attività disponibili.
  2. Fai clic sull'elemento Mappatura dei dati e posizionalo nell'Editor integrazioni.
  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 mappatura dati.
  6. Mappa la variabile di output Oracle—connectorOutputPayload (Fetch Oracle Data)—alla variabile di integrazione customer_record.

    Una volta completata la mappatura, chiudi il riquadro. Tutte le modifiche verranno salvate automaticamente.

  7. Aggiungi una connessione perimetrale dal connettore Recupera dati Oracle all'attività Recupera dati Oracle.

Aggiungi condizione limite

Una condizione limite consente di specificare le condizioni che devono essere soddisfatte affinché il controllo di un'integrazione venga trasferito 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 limite controlla il flusso dell'integrazione in base alla variabile di integrazione location:

  1. Aggiungi una connessione edge dal trigger API all'attività Mappa a MySQL con la seguente condizione edge: 
      $location$ = "US"
  2. Aggiungi un'altra connessione edge dal trigger API all'attività Mappa a Oracle con la seguente condizione edge: 
      $location$ = "APAC"

Flusso di integrazione di esempio

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

Immagine di esempio che mostra il flusso di integrazione Immagine di esempio che mostra il flusso di integrazione

Pubblica integrazione

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

Una volta pubblicata l'integrazione, puoi visualizzare e controllare i log di esecuzione dell'integrazione pubblicata. Per visualizzare i log, fai clic su Immagine che mostra l'icona dei log di esecuzioneVisualizza log di esecuzione per questa integrazione. Viene visualizzata la pagina Log di esecuzione.

Testare l'integrazione

Testare l'integrazione dall'Editor integrazioni

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

  1. Fai clic su Testa nella barra degli strumenti dell'Editor di integrazione.

    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 (Prova integrazione).

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

{ 
  "CUSTOMER_ID": 1,
  "CUSTOMER_NAME": "Amal"
  "CUSTOMER_EMAILID": "test-01@test.com "
  "CUSTOMER_CITY": "Delhi"
}

Per saperne di più sui test, consulta Testare e pubblicare le integrazioni.

Testare utilizzando una chiamata API REST

Ora che l'integrazione è pubblicata e in esecuzione, puoi richiamarla 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: effettuare una richiesta API con input personalizzati

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 di esecuzione dell'integrazione contenente il seguente JSON: 

  { 
    "CUSTOMER_ID": 2,
    "CUSTOMER_NAME": "Dana"
    "CUSTOMER_EMAILID": "test-02@test.com "
    "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 di integrazione. Per ulteriori informazioni, consulta la sezione Eliminare le integrazioni.
  • Per informazioni su come eliminare una connessione, vedi Gestire i connettori.