Crea un connettore personalizzato

In questa pagina viene descritto come creare un connettore personalizzato. Per comprendere che cos'è un connettore personalizzato, consulta la sezione Connettori personalizzati.

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

  1. Crea un connettore personalizzato - In questa attività definirai il contratto tra Integration Connectors e il tuo endpoint (backend) fornendo la specifica OpenAPI dell'endpoint. Attualmente sono supportate solo la versione 3.0 di OpenAPI e tutte le relative versioni secondarie. L'indicazione della specifica è un'attività una tantum.
  2. Crea una connessione del connettore personalizzata: in questa attività configurerai i dettagli della connessione del backend, come il nome host e l'autenticazione. Per uno specifico connettore personalizzato, puoi creare tutte le connessioni che vuoi.

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

Prima di iniziare

Assicurati che l'utente che crea il connettore personalizzato disponga di uno dei seguenti ruoli IAM:

Crea un connettore personalizzato

Come descritto negli scenari di connettività 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 intermediario.

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

Crea un connettore personalizzato 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 Connettori di integrazione > 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. Account di servizio: seleziona un account di servizio che abbia i ruoli richiesti.
    5. Logo: carica l'immagine in un bucket spazio di archiviazione sul cloud per utilizzarla come logo del connettore.
  4. Fai clic su Avanti.
  5. Nella sezione Specifiche 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 spazio di archiviazione sul cloud.
  6. Esamina i dettagli di configurazione del connettore e 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, verrà creata anche una prima versione del connettore. Puoi visualizzare i dettagli della versione nella scheda Versione della pagina Dettagli del connettore personalizzato. Per maggiori informazioni, vedi .

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

API

I comandi di esempio riportati di seguito mostrano come creare un connettore personalizzato utilizzando le API Integration Connectors:

  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 progetto Google Cloud.
    • UNIQUE_IDENTIFIER: un identificatore univoco del connettore. Ad esempio custom-connector-1.
  2. Configura la versione personalizzata del connettore. 
    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 OpenAPI. Ad esempio, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • VERSION_NUMBER: un numero di versione per il connettore. Ad esempio, 2.

Crea un connettore personalizzato 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 Connettori di integrazione > 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 mostrate 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 spazio di archiviazione sul cloud per utilizzarla come logo del connettore.
  4. Fai clic su Avanti.
  5. Nella sezione Specifiche 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 spazio di archiviazione sul cloud.
  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 su cui viene eseguito il servizio intermediario.
    3. Porta: inserisci il numero di porta del servizio intermediario.
  8. Fai clic su Avanti.
  9. Nella sezione Autenticazione connettore, seleziona il tipo di autenticazione del servizio intermedio, quindi inserisci i dettagli corrispondenti come richiesto. Questo passaggio consiste nel configurare l'autenticazione da Integration Connectors al servizio intermediario.

    La configurazione dell'autenticazione dal servizio intermedio al backend non può essere configurata in Integration Connectors; spetta al servizio intermediario come vuole eseguire l'autenticazione con il backend.

  10. Fai clic su Avanti.
  11. Nella sezione Variabili di backend, inserisci i valori che vuoi inviare al tuo backend tramite il servizio intermedio. Devi configurare i valori come coppia chiave-valore Parigi. Per inserire una coppia chiave-valore, fai clic su Aggiungi variabile, 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 in che modo il connettore deve inviare le variabili al servizio intermediario. Le opzioni disponibili sono Header, Request payload e Query parameter.
    • (Facoltativo) Seleziona Required per specificare che la variabile è una variabile obbligatoria.
  12. Fai clic su Avanti.
  13. Esamina i dettagli di configurazione del connettore e 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 del connettore. Puoi visualizzare i dettagli della versione nella scheda Versione della pagina Dettagli del connettore personalizzato. Per informazioni sulla creazione e sulla modifica di una versione personalizzata del connettore, consulta Gestire le versioni personalizzate del connettore.

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

API

I comandi di esempio riportati di seguito mostrano come creare un connettore personalizzato utilizzando le API Integration Connectors:

  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 progetto Google Cloud.
    • UNIQUE_IDENTIFIER: un identificatore univoco del connettore. Ad esempio custom-connector-1.
  2. Configura la versione personalizzata del connettore 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 OpenAPI. Ad esempio, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • 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 personalizzata

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

  1. Nella console Cloud, vai alla pagina Connettori di integrazione > Connessioni, quindi seleziona o crea un progetto Google Cloud.

    Vai alla pagina Connessioni

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

    Per l'elenco di tutte le aree geografiche supportate, consulta la sezione Località.

  4. Fai clic su Avanti.
  5. Nella sezione Dettagli connessione, imposta i seguenti campi:
    1. Connettore: seleziona il connettore personalizzato dall'elenco a discesa dei connettori disponibili.
    2. Versione 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 contenere più di 63 caratteri.
    4. Facoltativamente, inserisci una descrizione per la connessione.
    5. Facoltativamente, seleziona Abilita Cloud Logging per abilitare il cloud logging.
    6. Account di servizio: seleziona un account di servizio che abbia i ruoli richiesti.
    7. Facoltativamente, 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 un numero inferiore di transazioni. Per capire in che modo i nodi influiscono sui prezzi del connettore, consulta Prezzi dei nodi di connessione. Se non inserisci alcun valore, per impostazione predefinita il numero minimo di nodi viene impostato su 2 (per una migliore disponibilità) e il numero massimo di nodi viene impostato su 50.

    8. Facoltativamente, fai clic su Aggiungi etichetta per aggiungere un'etichetta alla connessione sotto forma di coppia chiave-valore.
  6. Fai clic su Avanti.
  7. Nella sezione Autenticazione, inserisci i dettagli di autenticazione per il backend.
    • Se ti connetti direttamente al tuo backend, Integration Connectors ti chiede di configurare l'autenticazione per il backend.
    • Se ti connetti indirettamente al backend tramite un servizio intermediario, Integration Connectors non richiede di configurare i dettagli di autenticazione. Quando crei il connettore, hai già configurato l'autenticazione tra Integration Connectors e il servizio intermediario. Integration Connectors non richiede la configurazione dell'autenticazione tra il servizio intermedio e il backend; spetta al servizio intermedio l'autenticazione con il backend.
  8. Fai clic su Avanti.
  9. Esamina i dettagli di configurazione della connessione e fai clic su Crea.

Se la creazione della connessione va a buon fine, viene elencata nella pagina Tutte le connessioni e la connessione diventa disponibile per Application Integration. Puoi utilizzare la connessione nell'integrazione tramite l'attività Connettori.

Considerazioni

Tieni presente i seguenti punti durante la creazione di un connettore personalizzato:

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