Questa pagina è stata tradotta dall'API Cloud Translation.

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à:

Crea un connettore personalizzato: in questa attività definirai il contratto tra Integration Connectors e l'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.
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 un connettore personalizzato specifico, puoi creare tutte le connessioni di cui hai bisogno.

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

Prima di iniziare

Per ottenere le autorizzazioni necessarie per creare il connettore personalizzato, chiedi all'amministratore di concederti Ruolo IAM Amministratore connettori personalizzati (roles/connectors.customConnectorAdmin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Attiva l'API Connector:
Attiva l'API Connector

Crea un connettore personalizzato

Come descritto nella sezione connettività di backend di connettività personalizzati, 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 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

Nella console, vai a alla pagina Connettori di integrazione > Connettori personalizzati, e poi selezionare o creare un progetto Google Cloud.
Vai alla pagina Connettori personalizzati
Fai clic su Crea nuovo per aprire la pagina Crea connettore personalizzato.
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.
  Nota: assicurati che la prevenzione dell'accesso pubblico sia disattivata per il bucket Cloud Storage.
Fai clic su Avanti.
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.
Esamina i dettagli di configurazione del connettore e poi fai clic su Crea.

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

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 personalizzata.

API

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

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.

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"

Sostituisci quanto segue:

SPECIFICATION_URL: l'URL della specifica OpenAPI. Per 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 con connettività indiretta

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

Console

Nella console, vai alla pagina Connettori di integrazione > Connettori personalizzati, quindi seleziona o crea un progetto Google Cloud.
Vai alla pagina Connettori personalizzati
Fai clic su Crea nuovo per aprire la pagina Crea connettore personalizzato.
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 Cloud Storage per utilizzarla come logo del connettore.
  Nota: assicurati che la prevenzione dell'accesso pubblico sia disabilitata nel bucket Cloud Storage.
Fai clic su Avanti.
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.
Fai clic su Avanti.
Nella sezione Destinazione del 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.
Fai clic su Avanti.
Nella sezione Autenticazione connettore, seleziona il tipo di autenticazione del servizio intermediario inserisci i dettagli corrispondenti come richiesto. Questo passaggio serve a configurare l'autenticazione da Integration Connectors al servizio intermediario.
La configurazione dell'autenticazione dal servizio intermediario al backend non può essere configurata in Integration Connectors; è compito del servizio intermediario decidere come eseguire l'autenticazione con il backend.
Fai clic su Avanti.
Nella sezione Voci di backend, inserisci i valori che vuoi inviare al tuo backend tramite il servizio intermediario. Tu deve configurare i valori come coppia chiave-valore Parigi. 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 la modalità di invio del connettore. le variabili al servizio intermediario. Le opzioni disponibili are; Header, Request payload e Query parameter.
- Se vuoi, seleziona Required per specificare che la variabile è obbligatoria.
Nota: ti verrà chiesto di inserire i valori le variabili configurate durante la creazione di una connessione.
Fai clic su Avanti.
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. 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.

API

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

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.

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"

Sostituisci quanto segue:

SPECIFICATION_URL: l'URL della specifica OpenAPI. Per 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.

Nota: questa chiamata API di esempio utilizza l'autenticazione Username and Password. In base alle tue esigenze, puoi utilizzare un tipo di autenticazione diverso.

Crea una connessione del connettore personalizzata

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:

Nella console Cloud, vai alla pagina Connettori di integrazione > Connessioni, quindi seleziona o crea un progetto Google Cloud.
Vai alla pagina Connessioni
Fai clic su Crea nuovo per aprire la pagina Crea connessione.
Nella sezione Località, seleziona una località per la connessione dal campo Regione.
Per l'elenco di tutte le regioni supportate, consulta Località.
Fai clic su Avanti.
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. (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, 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 migliore 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.
Fai clic su Avanti.
Nella sezione Autenticazione, inserisci i dettagli di autenticazione per il tuo backend.
- Se ti connetti direttamente al tuo backend, Integration Connectors ti chiede per 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, avrai già configurato l'autenticazione tra i connettori di integrazione e il servizio intermediario. Integration Connectors non richiede la configurazione dell'autenticazione tra il servizio intermediario e il backend; la responsabilità dell'intermediario su come vuole autenticarsi con il backend.
Fai clic su Avanti.
Esamina i dettagli di configurazione della connessione e fai clic su Crea.

Se la creazione della connessione è andata a buon fine, viene elencata nella pagina Tutte le connessioni e diventa disponibile in Integrazione applicazioni. Puoi usare la connessione nell'integrazione tramite l'attività Connettori.

Considerazioni

Tieni presente i seguenti punti quando crei un connettore personalizzato:

Integration Connectors 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 creare una connessione per il connettore personalizzato, Integration Connectors convalida la specifica e Se ci sono errori, la connessione sarà nello stato Error.
Integration Connectors 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 progetti Google Cloud in cui sono attivati 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.