Consulta i connettori supportati per Application Integration.

Creare un connettore personalizzato

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

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

  1. Crea un connettore personalizzato: in questa attività, dovrai definire il contratto tra l'integrazione di applicazioni e il tuo endpoint (backend) fornendo la specifica OpenAPI dell'endpoint. Al momento, è supportata solo la versione 3.0 di OpenAPI e tutte le relative versioni secondarie. La specifica della specifica è un'attività una tantum.
  2. Crea una connessione del connettore personalizzato: in questa attività, configurerai i dettagli di connessione del tuo backend, ad esempio il nome host e l'autenticazione. Per un connettore personalizzato specifico, puoi creare tutte le connessioni necessarie.

Per comprendere la differenza tra un connettore e una connessione, consulta Connettore e connessione.

Prima di iniziare

Creare un connettore personalizzato

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

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

I passaggi per la creazione del connettore personalizzato variano leggermente per questi due pattern.

Creare con connettività diretta

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

Console

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

    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. Account di servizio: seleziona un account di servizio con i 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 Specifiche 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 della specifica in un bucket Cloud Storage.
  6. Esamina i dettagli di configurazione del connettore e poi fai clic su Crea.

Se la creazione del connettore va a buon fine, il connettore appena creato verrà visualizzato nella pagina Connettori personalizzati e, se si tratta di un nuovo connettore, verrà creata anche una prima versione. Puoi visualizzare i dettagli della versione nella scheda Versione della pagina Dettagli del connettore personalizzato. Per ulteriori informazioni, consulta .

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

API

I seguenti comandi di esempio mostrano come creare un connettore personalizzato utilizzando le API di integrazione delle applicazioni:

  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 del connettore. Ad esempio, 2.

Creare con connettività indiretta

Per creare un connettore personalizzato che si connette al tuo backend tramite un endpoint intermedio:

Console

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

    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: abilita questa opzione. Vengono visualizzate le sezioni di configurazione aggiuntive nella pagina.
    5. Account di servizio: 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 Specifiche 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 della specifica in un bucket Cloud Storage.
  6. Fai clic su Avanti.
  7. Nella sezione Destinazione del connettore, imposta i seguenti campi:
    1. Tipo di destinazione: seleziona Indirizzo host.
    2. Host: inserisci il nome host su cui è in esecuzione il servizio intermediario.
    3. Porta: inserisci il numero di porta del servizio intermediario.
  8. Fai clic su Avanti.
  9. Nella sezione Autenticazione del connettore, seleziona il tipo di autenticazione del servizio intermediario, quindi inserisci i dettagli corrispondenti come richiesto. Questo passaggio serve a configurare l'autenticazione dall'integrazione dell'applicazione al servizio intermediario.

    La configurazione dell'autenticazione dal servizio intermediario al backend non può essere configurata nell'integrazione delle applicazioni. È compito del servizio intermediario scegliere come eseguire l'autenticazione con il backend.

    Per l'autenticazione al servizio intermediario puoi utilizzare i seguenti tipi di autenticazione:

    • Autenticazione dell'account di servizio
    • Autenticazione tramite 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 non è limitato e non richiede alcuna autenticazione, seleziona Nessuna autenticazione.

  10. Fai clic su Avanti.
  11. Nella sezione Voci di backend, inserisci i valori che vuoi inviare al tuo 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 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 in che modo vuoi che il connettore invii le variabili al servizio intermediario. Le opzioni disponibili sono Header, Request payload e Query parameter.
    • Se vuoi, seleziona Required per specificare che la variabile è obbligatoria.
  12. Fai clic su Avanti.
  13. Esamina i dettagli di configurazione del connettore e poi fai clic su Crea.

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

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

Configura autenticazione

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

  • Autenticazione dell'account di servizio

    Seleziona questa opzione per eseguire l'autenticazione utilizzando un account di servizio Google Cloud. Assicurati di aver fornito all'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, consulta Ambiti di accesso.
  • Autenticazione con chiave API

    Seleziona questa opzione per eseguire l'autenticazione utilizzando una chiave API.

    • Chiave API: seleziona l'API 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 inserito qui verrà utilizzato come nome della chiave per la chiave API selezionata in precedenza.
    • Posizione della chiave API: seleziona dove vuoi aggiungere la chiave API nella richiesta.
  • OAuth 2.0 - Autenticazione delle credenziali client
    • ID client: l'ID client da utilizzare per l'autenticazione al servizio intermediario.
    • Client secret: il secret di Secret Manager contenente il client secret per l'autenticazione al servizio intermediario.
    • Formato della richiesta per il token di accesso: il formato della richiesta da utilizzare nelle richieste effettuate per recuperare il token di accesso dal server di autenticazione. Seleziona body per passare l'ID cliente e il segreto come corpo della richiesta oppure header per passarli come intestazione codificata.
    • Percorso richiesta token: percorso 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 segreto 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 segreto 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 di integrazione delle applicazioni:

  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.

Creare una connessione con un 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. Se vuoi, seleziona Attiva Cloud Logging per attivare il logging sul cloud.
    6. Account di servizio: seleziona un account di servizio che abbia i 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, al contrario, sono necessari meno nodi per elaborare meno transazioni. Per capire in che modo i nodi influiscono sui prezzi dei connettori, consulta Prezzi per i nodi di connessione. Se non inserisci alcun valore, per impostazione predefinita il numero minimo di nodi è impostato su 2 (per una maggiore disponibilità) e il numero massimo di nodi è impostato su 50.

    8. Se vuoi, fai clic su Aggiungi etichetta per aggiungere un'etichetta alla connessione sotto forma di coppia chiave-valore.
  5. Fai clic su Avanti.
  6. Nella sezione Autenticazione, inserisci i dettagli di autenticazione per il tuo backend.
    • Se ti connetti direttamente al backend, Application Integration ti chiede di configurare l'autenticazione per il backend.
    • Se ti connetti indirettamente al tuo backend tramite un servizio intermediario, Application Integration non ti chiede di configurare i dettagli di autenticazione. Quando crei il connettore, avrai già configurato l'autenticazione tra Application Integration e il servizio intermediario. L'integrazione delle applicazioni non richiede la configurazione dell'autenticazione tra il servizio intermediario e il backend. Spetta al servizio intermediario decidere in che modo autenticarsi con il backend.
  7. Fai clic su Avanti.
  8. Esamina i dettagli di configurazione della connessione e poi fai clic su Crea.

Se la creazione della connessione è andata a buon fine, viene elencata nella pagina Tutte le connessioni e diventa disponibile per l'integrazione delle applicazioni. Puoi utilizzare la connessione nell'integrazione tramite l'attività Connectors.

Considerazioni

Tieni presente i seguenti punti quando crei un connettore personalizzato:

  • Application Integration supporta solo la versione 3.0 di OpenAPI 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 sono presenti errori, la connessione sarà nello stato Error.
  • L'integrazione delle applicazioni non distingue tra entità e azioni. Di conseguenza, sia le entità sia le azioni del tuo backend verranno elencate come Actions nel connettore personalizzato.
  • I connettori personalizzati non sono supportati nei Google Cloud progetti 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 con il tuo backend.
  • Il tipo di contenuti multimediali suddivisi in più parti non è supportato nella specifica Open API.
  • 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