Consulta i connettori supportati per Application Integration.

Crea un connettore personalizzato

Questa pagina descrive come creare un connettore personalizzato. Per capire cos'è un connettore personalizzato, vedi Connettori personalizzati.

Per stabilire la connettività al backend utilizzando un connettore personalizzato, devi svolgere le seguenti attività:

  1. Crea un connettore personalizzato: in questa attività definirai il contratto tra Application Integration e il tuo endpoint (backend) fornendo la specifica OpenAPI dell'endpoint. Al momento, sono supportate solo la versione 3.0 di OpenAPI e tutte le relative versioni secondarie. La specifica è un'attività una tantum.
  2. Crea una connessione del connettore personalizzato: in questa attività configurerai i dettagli di connessione del backend, come nome host e autenticazione. Per un connettore personalizzato specifico, puoi creare tutte le connessioni che ti servono.

Per capire la differenza tra un connettore e una connessione, vedi Connettore e connessione.

Prima di iniziare

Crea un connettore personalizzato

Come descritto negli scenari di connettività di backend, i connettori personalizzati possono avere uno dei seguenti pattern di connettività:

  • Connettività diretta all'endpoint pubblico del backend.
  • Connettività indiretta al backend tramite un endpoint pubblico intermedio.

I passaggi per la creazione di connettori personalizzati variano leggermente per questi due pattern.

Crea con la connettività diretta

Per creare un connettore personalizzato con connettività diretta all'endpoint del backend, segui questi passaggi:

Console

  1. Nella console, vai alla pagina Integrazione applicazioni > Connettori personalizzati, quindi seleziona o crea un progetto Google Cloud .

    Vai alla pagina Connettori personalizzati

  2. Fai clic su Crea nuovo per aprire la pagina Crea connettore personalizzato.
  3. Nella sezione Dettagli connettore, imposta i seguenti campi:
    1. Nome connettore: inserisci un nome per il connettore.
    2. Nome visualizzato: inserisci un nome visualizzato per il connettore.
    3. Descrizione: inserisci una descrizione.
    4. Service account: seleziona un account di servizio che disponga dei ruoli richiesti.
    5. Logo: carica l'immagine in un bucket Cloud Storage per utilizzarla come logo del connettore.
  4. Fai clic su Avanti.
  5. Nella sezione Specifica del connettore, imposta i seguenti campi:
    1. Tipo di connettore personalizzato: seleziona il tipo di connettore personalizzato.
    2. Specifica del connettore: inserisci l'URL pubblico della specifica OpenAPI o carica il file di specifica in un bucket Cloud Storage.
  6. Esamina i dettagli di configurazione del connettore, quindi fai clic su Crea.

Se la creazione del connettore ha esito positivo, il connettore appena creato verrà visualizzato nella pagina Vai alla pagina Connettori personalizzati e, se si tratta di un nuovo connettore, viene creata anche una prima versione del connettore. Puoi visualizzare i dettagli della versione nella scheda Versione della pagina Dettagli connettore personalizzato. Per ulteriori informazioni, vedi .

Tuttavia, tieni presente che per connetterti al backend, devi creare una connessione per il connettore appena creato. Per ulteriori informazioni, vedi Creare una connessione del connettore personalizzato.

API

I seguenti comandi di esempio mostrano come creare un connettore personalizzato utilizzando le API Application Integration:

  1. Crea il connettore. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    Sostituisci quanto segue:

    • CUSTOM_CONNECTOR_NAME: Un nome per il connettore personalizzato.
    • PROJECT_ID: l'ID del tuo Google Cloud progetto.
    • UNIQUE_IDENTIFIER: un identificatore univoco per il connettore. Ad esempio custom-connector-1.
  2. Configura la versione del connettore personalizzato. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL",}' \
"https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"

    3. Sostituisci quanto segue:

    • SPECIFICATION_URL: l'URL della specifica Open API. Ad esempio, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: l'ID del tuo Google Cloud progetto.
    • VERSION_NUMBER: un numero di versione per il connettore. Ad esempio, 2.

Crea con connettività indiretta

Per creare un connettore personalizzato che si connette al backend tramite un endpoint intermedio, segui questi passaggi:

Console

  1. Nella console, vai alla pagina Integrazione applicazioni > Connettori personalizzati, quindi seleziona o crea un progetto Google Cloud .

    Vai alla pagina Connettori personalizzati

  2. Fai clic su Crea nuovo per aprire la pagina Crea connettore personalizzato.
  3. Nella sezione Dettagli connettore, imposta i seguenti campi:
    1. Nome connettore: inserisci un nome per il connettore.
    2. Nome visualizzato: inserisci un nome visualizzato per il connettore.
    3. Descrizione: inserisci una descrizione.
    4. Configura la destinazione del connettore per l'accesso al backend: attiva questa opzione. Vengono visualizzate le sezioni di configurazione aggiuntive nella pagina.
    5. Service account: seleziona un account di servizio con i ruoli richiesti.
    6. Logo: carica l'immagine in un bucket Cloud Storage per utilizzarla come logo del connettore.
  4. Fai clic su Avanti.
  5. Nella sezione Specifica del connettore, imposta i seguenti campi:
    1. Tipo di connettore personalizzato: seleziona il tipo di connettore personalizzato.
    2. Specifica del connettore: inserisci l'URL pubblico della specifica OpenAPI o carica il file di specifica in un bucket Cloud Storage.
  6. Fai clic su Avanti.
  7. Nella sezione Destinazione connettore, imposta i seguenti campi:
    1. Tipo di destinazione: seleziona Indirizzo host.
    2. Host: inserisci il nome host in cui è in esecuzione il servizio intermediario e includi lo schema http:// o https://.
    3. Porta: inserisci il numero di porta del tuo servizio intermediario.
  8. Fai clic su Avanti.
  9. Nella sezione Autenticazione connettore, seleziona il tipo di autenticazione del servizio intermediario, quindi inserisci i dettagli corrispondenti come richiesto. Questo passaggio serve a configurare l'autenticazione da Application Integration al servizio intermediario.

    La configurazione dell'autenticazione dal servizio intermediario al backend non può essere configurata in Application Integration; spetta al servizio intermediario decidere come autenticarsi con il backend.

    Puoi utilizzare i seguenti tipi di autenticazione per autenticarti al servizio intermediario:

    • Autenticazione dell'account di servizio
    • Autenticazione con chiave API
    • OAuth 2.0 - Autenticazione delle credenziali client
    • Autenticazione di base
    • Autenticazione digest

      • Per capire come configurare questi tipi di autenticazione, consulta Configurare l'autenticazione.

    Se l'accesso alle risorse dell'API è senza restrizioni e non richiede alcuna autenticazione, seleziona Nessuna autenticazione.

  10. Fai clic su Avanti.
  11. Nella sezione Variabili di backend, inserisci i valori che vuoi inviare al backend tramite il servizio intermediario. Devi configurare i valori come coppie chiave-valore. Per inserire una coppia chiave-valore, fai clic su Aggiungi variabile e poi imposta i seguenti campi:
    • Chiave: inserisci il nome della chiave.
    • Tipo di valore: seleziona il tipo di dati della variabile.
    • Nome visualizzato: inserisci un nome visualizzato.
    • Posizione: specifica la modalità di invio delle variabili al servizio intermediario da parte del connettore. Le opzioni disponibili sono Header, Request payload e Query parameter.
    • (Facoltativo) Seleziona Required per specificare che la variabile è obbligatoria.
  12. Fai clic su Avanti.
  13. Esamina i dettagli di configurazione del connettore, quindi fai clic su Crea.

Se la creazione del connettore va a buon fine, il connettore appena creato viene visualizzato nella pagina Connettori personalizzati e, se si tratta di un nuovo connettore, viene creata anche una prima versione del connettore. Puoi visualizzare i dettagli della versione nella scheda Versione della pagina Dettagli connettore personalizzato. Per informazioni su come creare e modificare una versione del connettore personalizzato, vedi Gestire le versioni del connettore personalizzato.

Tuttavia, tieni presente che per connetterti al backend, devi creare una connessione per il connettore appena creato. Per ulteriori informazioni, vedi Creare una connessione del connettore personalizzato.

Configura l'autenticazione

Inserisci i dettagli in base all'autenticazione che vuoi utilizzare.

  • Autenticazione del service account

    Seleziona questa opzione per l'autenticazione utilizzando un account di servizio Google Cloud. Assicurati di aver fornito al account di servizio i ruoli e le autorizzazioni IAM pertinenti richiesti per l'autenticazione.

    • Ambiti: seleziona gli ambiti OAuth 2.0 richiesti dal menu a discesa. Per ulteriori informazioni, vedi Ambiti di accesso.
  • Autenticazione con chiave API

    Seleziona questa opzione per l'autenticazione tramite una chiave API.

    • Chiave API: seleziona il secret di Secret Manager della chiave API.
    • Versione del secret: seleziona la versione del secret.
    • Nome parametro chiave API: inserisci un nome parametro per la chiave API. Una chiave API viene inviata al server di backend come coppia chiave-valore. Il valore che inserisci qui verrà utilizzato come nome della chiave per la chiave API che hai selezionato in precedenza.
    • Posizione della chiave API: seleziona dove vuoi aggiungere la chiave API nella richiesta.
  • OAuth 2.0 - Concessione delle credenziali client
    • ID client: l'ID client da utilizzare per l'autenticazione al servizio intermediario.
    • Client secret: secret di Secret Manager contenente il client secret per l'autenticazione al servizio intermediario.
    • Formato della richiesta per il token di accesso: formato della richiesta da utilizzare nelle richieste effettuate per recuperare il token di accesso dal server di autenticazione. Seleziona body per trasmettere l'ID client e il client secret come corpo della richiesta oppure header per trasmetterli come intestazione codificata.
    • Token Request Path (Percorso richiesta token): percorso della richiesta da aggiungere all'URL del server di autenticazione per recuperare l'URL del token di accesso.
  • Autenticazione di base
    • Nome utente: nome utente utilizzato per l'autenticazione al servizio intermediario.
    • Password: il secret di Secret Manager contenente la password associata al nome utente fornito.
  • Autenticazione Digest
    • Nome utente: nome utente utilizzato per l'autenticazione al servizio intermediario.
    • Password: il secret di Secret Manager contenente la password associata al nome utente fornito.

API

I seguenti comandi di esempio mostrano come creare un connettore personalizzato utilizzando le API Application Integration:

  1. Crea il connettore. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"
-d '{"customConnectorType":"OPEN_API", \
"displayName":"CUSTOM_CONNECTOR_NAME", \
"description": "an open api based custom connector for hrms"}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"

    Sostituisci quanto segue:

    • CUSTOM_CONNECTOR_NAME: Un nome per il connettore personalizzato.
    • PROJECT_ID: l'ID del tuo Google Cloud progetto.
    • UNIQUE_IDENTIFIER: un identificatore univoco per il connettore. Ad esempio custom-connector-1.
  2. Configura la versione del connettore personalizzato e l'autenticazione. 
    curl -X POST \
-H "authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"spec_location": "SPECIFICATION_URL", \
"service_account":"test-sa", \
"enable_backend_destination_config": true, \
"auth_config": { \
"auth_type":"USER_PASSWORD", \
"auth_key": "basic", \
"user_password": { \
"username":"USERNAME", \
"password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
}}, \
"backend_variable_templates": [{ \
"key":"authkey", \
"value_type":"SECRET", \
"display_name":"Authorization Key", \
"required":true, \
"location_type": "HEADER" \
}], \
"destination_configs":[{ \
"key":"base_url", \
"destinations": [{ \
"host":"DESTINATION_HOST_ADDRESS" \
}]} \
]}' \
"https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"

    3. Sostituisci quanto segue:

    • SPECIFICATION_URL: l'URL della specifica Open API. Ad esempio, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: l'ID del tuo Google Cloud progetto.
    • USERNAME: Nome utente per l'autenticazione con il servizio intermediario.
    • SECRET_VERSION_NUMBER: Il numero di versione del secret di Secret Manager. Ad esempio, 2.
    • DESTINATION_HOST_ADDRESS: Indirizzo host del servizio intermediario. Ad esempio, http://www.test.com:80.
    • CONNECTOR_VERSION_NUMBER: Il numero di versione del connettore personalizzato. Ad esempio, 1.

Crea una connessione del connettore personalizzato

Dopo aver creato il connettore personalizzato, per connetterti al backend devi creare una connessione del tipo di connettore personalizzato. Di seguito sono riportati i passaggi di alto livello per creare una nuova connessione:

  1. Fai clic su Crea nuovo per aprire la pagina Crea connessione.
  2. Nella sezione Località, seleziona una località per la connessione dal campo Regione.

    Per l'elenco di tutte le regioni supportate, consulta Località.

  3. Fai clic su Avanti.
  4. Nella sezione Dettagli connessione, imposta i seguenti campi:
    1. Connettore: seleziona il connettore personalizzato dall'elenco a discesa dei connettori disponibili.
    2. Versione del connettore: seleziona la versione del connettore dall'elenco a discesa delle versioni disponibili.
    3. Nel campo Nome connessione, inserisci un nome per la connessione.

      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 la connessione.
    5. (Facoltativo) Seleziona Abilita Cloud Logging per attivare Cloud Logging.
    6. Service account: seleziona un account di servizio che disponga dei ruoli richiesti.
    7. (Facoltativo) Configura le impostazioni del nodo di connessione:

      • Numero minimo di nodi: inserisci il numero minimo di nodi di connessione.
      • Numero massimo di nodi: inserisci il numero massimo di nodi di connessione.

      Un nodo è un'unità (o una replica) di una connessione che elabora le transazioni. Sono necessari più nodi per elaborare più transazioni per una connessione e, viceversa, sono necessari meno nodi per elaborare meno transazioni. Per capire in che modo i nodi influiscono sui prezzi dei connettori, consulta la sezione Prezzi dei nodi di connessione. Se non inserisci alcun valore, per impostazione predefinita i nodi minimi sono impostati su 2 (per una migliore disponibilità) e i nodi massimi su 50.

    8. (Facoltativo) Fai clic su Aggiungi etichetta per aggiungere un'etichetta alla connessione sotto forma di coppia chiave-valore.
  5. Fai clic su Avanti.
  6. Se il connettore utilizza un servizio intermediario per connettersi al backend, procedi nel seguente modo:

    Nella sezione Destinazioni, imposta i seguenti campi:

    1. Tipo di destinazione: seleziona Indirizzo host.
    2. Host: inserisci il nome host in cui è in esecuzione il servizio intermediario e includi lo schema http:// o https://.
    3. Porta: inserisci il numero di porta del tuo servizio intermediario.

    Per impostazione predefinita, il campo di destinazione contiene l'URL della specifica OpenAPI. Quando esistono più URL del server, viene visualizzato il primo.

  7. Fai clic su Avanti.
  8. Nella sezione Autenticazione, inserisci i dettagli di autenticazione per il backend.
    • Se ti connetti direttamente al backend, Application Integration ti chiede di configurare l'autenticazione per il backend.
    • Se ti connetti indirettamente al backend tramite un servizio intermediario, Application Integration non ti chiede di configurare i dettagli di autenticazione. Quando crei il connettore, hai già configurato l'autenticazione tra Application Integration e il servizio intermediario. Application Integration non richiede la configurazione dell'autenticazione tra il servizio intermediario e il backend. Spetta al servizio intermediario decidere come autenticarsi con il backend.
  9. Fai clic su Avanti.
  10. Esamina i dettagli della configurazione della connessione, poi fai clic su Crea.

Se la creazione della connessione ha esito positivo, viene elencata nella pagina Tutte le connessioni e diventa disponibile in Application Integration. Puoi utilizzare la connessione nell'integrazione tramite l'attività Connettori.

Considerazioni

Quando crei un connettore personalizzato, tieni presente quanto segue:

  • Application Integration supporta solo OpenAPI versione 3.0 e tutte le relative versioni secondarie.
  • La specifica Open API non viene convalidata durante la creazione del connettore personalizzato. Quando crei una connessione per il connettore personalizzato, Application Integration convalida la specifica e, se presenta errori, la connessione sarà nello stato Error.
  • Application Integration non distingue tra entità e azioni. Pertanto, sia le entità che le azioni del backend verranno elencate come Actions nel connettore personalizzato.
  • I connettori personalizzati non sono supportati nei progetti Google Cloud in cui sono abilitati i Controlli di servizio VPC.
  • Sia l'endpoint della specifica Open API sia l'endpoint di backend devono essere accessibili pubblicamente. Ciò significa che non puoi stabilire una connettività privata al backend.
  • Il tipo di media in più parti non è supportato nella specifica dell'API aperta.
  • Non puoi modificare i dettagli della versione di un connettore personalizzato.

Quote e limiti

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

Passaggi successivi