Oracle DB (versione 2)

Il connettore Oracle DB consente di connettersi a un'istanza di database Oracle (versione 11.2 o successive) ed eseguire le operazioni di database supportate.

Prima di iniziare

Prima di utilizzare il connettore Oracle DB, esegui queste attività:

  • Nel tuo progetto Google Cloud:
    • Concedi il ruolo IAM roles/connectors.admin all'utente che configura il connettore.
    • Concedi i seguenti ruoli IAM all'account di servizio che vuoi utilizzare per il connettore:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      Un account di servizio è un tipo speciale di Account Google destinato a rappresentare un utente "non umano" che deve autenticarsi ed essere autorizzato ad accedere ai dati nelle API di Google. Se non hai un account di servizio, devi crearne uno. Per saperne di più, consulta la pagina sulla creazione di un account di servizio.

    • Abilita i seguenti servizi:
      • secretmanager.googleapis.com (API Secret Manager)
      • connectors.googleapis.com (API Connectors)

      Per informazioni su come abilitare i servizi, vedi Abilitazione dei servizi.

    Se questi servizi o queste autorizzazioni non sono stati abilitati per il tuo progetto in precedenza, ti verrà chiesto di abilitarli durante la configurazione del connettore.

Configura il connettore

Per configurare il connettore è necessario creare una connessione all'origine dati (sistema di backend). Una connessione è specifica per un'origine dati. Ciò significa che se disponi di molte origini dati, devi creare una connessione separata per ciascuna. Per creare una connessione, segui questi passaggi:

  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 Posizione, scegli la località per la connessione.
    1. Regione: seleziona una località dall'elenco a discesa.

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

    2. Tocca Avanti.
  4. Nella sezione Dettagli connessione, completa quanto segue:
    1. Connettore: seleziona Oracle DB dall'elenco a discesa dei connettori disponibili.
    2. Versione connettore: seleziona la versione 2 dall'elenco a discesa delle versioni disponibili.
    3. Nel campo Nome connessione, inserisci un nome per l'istanza di 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 l'istanza di connessione.
    5. (Facoltativo) Seleziona Abilita Cloud Logging per abilitare Cloud Logging.
    6. Account di servizio: seleziona un account di servizio con 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 minore 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 è impostato su 2 (per una migliore disponibilità) e il numero massimo di nodi è impostato su 50.

    8. ServiceName: il nome del servizio del database Oracle.
    9. DataSource: nome Oracle Net Services, Connect Descriptor (noto anche come stringa TNS Connect) o una denominazione di connessione semplice che identifica il database a cui connettersi.
    10. (Facoltativo) Seleziona Includi sinonimi.
    11. Timeout connessione abbandonata: inserisci il valore di timeout (in secondi) che specifica per quanto tempo una connessione presa in prestito può rimanere inutilizzata prima di essere considerata abbandonata.
    12. Timeout connessione inattiva: inserisci il valore di timeout della connessione (in secondi).
    13. Tempo massimo di riutilizzo della connessione: inserisci il tempo di riutilizzo della connessione (in secondi).
    14. Timeout connessione TTL: inserisci il tempo massimo (in secondi) durante il quale la connessione può rimanere in uso.
    15. Schemi sfogliabili: inserisci i nomi degli schemi separati da virgole da utilizzare per il recupero di entità e azioni. Ad esempio, schemaA, schemaB, schemaC.
    16. Facoltativamente, fai clic su + AGGIUNGI ETICHETTA per aggiungere un'etichetta alla connessione sotto forma di coppia chiave-valore.
    17. Fai clic su AVANTI.
  5. Nella sezione Destinazioni, inserisci i dettagli dell'host remoto (sistema di backend) a cui vuoi connetterti.
    1. Tipo di destinazione: seleziona un Tipo di destinazione.
      1. Nel campo Indirizzo host, specifica il nome host o l'indirizzo IP della destinazione.
        1. Se vuoi stabilire una connessione privata ai sistemi di backend, segui questi passaggi:
          1. Crea un collegamento al servizio PSC.
          2. Crea un collegamento endpoint e inserisci i relativi dettagli nel campo Indirizzo host.
        2. Se vuoi stabilire una connessione pubblica ai tuoi sistemi di backend con maggiore sicurezza, puoi configurare indirizzi IP statici in uscita per le tue connessioni, quindi configurare le regole firewall in modo da inserire nella lista consentita solo indirizzi IP statici specifici.

      Per inserire altre destinazioni, fai clic su +AGGIUNGI DESTINAZIONE.

    2. Fai clic su AVANTI.
  6. Nella sezione Autenticazione, inserisci i dettagli di autenticazione.
    1. Seleziona un Tipo di autenticazione e inserisci i dettagli pertinenti.

      La connessione Oracle DB supporta i seguenti tipi di autenticazione:

      • Nome utente e password

      2. Per informazioni su come configurare questi tipi di autenticazione, vedi Configurare l'autenticazione.

    2. Fai clic su AVANTI.
  7. Verifica: controlla i dettagli di connessione e autenticazione.
  8. Fai clic su Crea.

Configura l'autenticazione

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

  • Nome utente e password
    • Nome utente: nome utente dell'account Oracle utilizzato per l'autenticazione
    • Password: il secret di Secret Manager contenente la password associata al nome utente dell'account Oracle.

Entità, operazioni e azioni

Tutti i connettori di integrazione forniscono un livello di astrazione per gli oggetti dell'applicazione connessa. Puoi accedere agli oggetti di un'applicazione solo tramite questa astrazione. L'astrazione è esposta come entità, operazioni e azioni.

  • Entità: un'entità può essere considerata come un oggetto o una raccolta di proprietà nell'applicazione o nel servizio collegato. La definizione di un'entità è diversa da un connettore a un connettore. Ad esempio, in un connettore di database, le tabelle sono le entità, in un connettore di file server, le cartelle sono le entità e in un connettore di sistema di messaggistica le code sono le entità.

    Tuttavia, è possibile che un connettore non supporti o non abbia entità, nel qual caso l'elenco Entities sarà vuoto.

  • Operazione : un'operazione è l'attività che puoi eseguire su un'entità. Su un'entità puoi eseguire una qualsiasi delle seguenti operazioni:

    Se selezioni un'entità dall'elenco disponibile, viene generato un elenco di operazioni disponibili per l'entità. Per una descrizione dettagliata delle operazioni, consulta le operazioni delle entità dell'attività Connettori. Tuttavia, se un connettore non supporta nessuna delle operazioni delle entità, queste operazioni non supportate non sono elencate nell'elenco Operations.

  • Azione: un'azione è una funzione di prima classe resa disponibile per l'integrazione attraverso l'interfaccia del connettore. Un'azione consente di apportare modifiche a una o più entità e di variare da connettore a connettore. Tuttavia, è possibile che un connettore non supporti alcuna azione, nel qual caso l'elenco Actions sarà vuoto.

Limitazioni di sistema

Il connettore Oracle DB può elaborare un massimo di 70 transazioni al secondo per nodo e limitare le transazioni oltre questo limite. Per impostazione predefinita, Integration Connectors alloca 2 nodi (per una migliore disponibilità) per una connessione.

Per informazioni sui limiti applicabili a Integration Connectors, consulta Limiti.

Tipi di dati supportati

Di seguito sono riportati i tipi di dati supportati per questo connettore:

  • GRANDE
  • BINARIO
  • BIT
  • BOOLEANO
  • CHAR
  • DATA
  • DECIMALE
  • DOPPIO
  • FLOAT
  • INTEGER
  • LUNGON VARCHAR
  • VARCHAR LUNGO
  • NCHAR
  • NUMERIC
  • NVARCHAR
  • VERO
  • INTENZIONE PICCOLA
  • TEMPO
  • TIMESTAMP
  • TINY INT
  • VAR.BINARIO
  • VARCHAR

Azioni

Il connettore Oracle DB ti consente di eseguire stored procedure, funzioni e query SQL personalizzate nel formato supportato dal tuo database Oracle. Per eseguire query SQL personalizzate, il connettore fornisce l'azione Esegui query personalizzata.

Per creare una query personalizzata:

  1. Segui le istruzioni dettagliate per aggiungere un'attività dei connettori.
  2. Quando configuri l'attività del connettore, seleziona Azioni nel tipo di azione da eseguire.
  3. Nell'elenco Azione, seleziona Esegui query personalizzata e fai clic su Fine.
  4. Espandi la sezione Input attività, quindi segui questi passaggi:
    1. Nel campo Timeout dopo, inserisci il numero di secondi di attesa prima dell'esecuzione della query.

      Valore predefinito: 180 secondi.

    2. Nel campo Numero massimo di righe, inserisci il numero massimo di righe da restituire dal database.

      Valore predefinito: 25.

    3. Per aggiornare la query personalizzata, fai clic su Modifica query personalizzata. Si apre la finestra di dialogo Editor di script.
    4. Nella finestra di dialogo Editor di script, inserisci la query SQL e fai clic su Salva.

      Puoi utilizzare un punto interrogativo (?) in un'istruzione SQL per rappresentare un singolo parametro che deve essere specificato nell'elenco parametri di ricerca. Ad esempio, la seguente query SQL seleziona tutte le righe della tabella Employees che corrispondono ai valori specificati per la colonna LastName: 

      SELECT * FROM Employees where LastName=?

    5. Se hai utilizzato punti interrogativi nella query SQL, devi aggiungere il parametro facendo clic su + Aggiungi nome parametro per ciascun punto interrogativo. Durante l'esecuzione dell'integrazione, questi parametri sostituiscono i punti interrogativi (?) nella query SQL in modo sequenziale. Ad esempio, se hai aggiunto tre punti interrogativi (?), devi aggiungere tre parametri in ordine di sequenza. Per aggiungere parametri di ricerca:
      1. Nell'elenco Tipo, seleziona il tipo di dati del parametro.
      2. Nel campo Valore, inserisci il valore del parametro.
      3. Per aggiungere più parametri, fai clic su + Aggiungi parametro di ricerca.

Per capire come utilizzare l'azione di query personalizzata, consulta gli esempi di azioni.

Esempi di azioni

Questa sezione descrive come eseguire alcune delle azioni in questo connettore.

Esempio: eseguire un raggruppamento per query

  1. Nella finestra di dialogo Configura l'attività del connettore, seleziona Azioni.
  2. Seleziona l'azione Esegui query personalizzata e fai clic su Fine.
  3. Nella sezione Input attività dell'attività Connettori, fai clic su Modifica query personalizzata. Viene visualizzata la finestra di dialogo Query personalizzata.
  4. Nella finestra di dialogo Query personalizzata, inserisci la seguente query SQL e fai clic su Salva: 
          Select E.EMPLOYEE_ID, E.EMPLOYEE_NAME, E.CITY
      FROM EMPLOYEES E
      LEFT JOIN EMPLOYEE_DEPARTMENT ED ON E.EMPLOYEE_ID=ED.ID
      WHERE E.EMPLOYEE_NAME = 'John'
      GROUP BY E.CITY,E.EMPLOYEE_ID,E.EMPLOYEE_NAME

    Questo esempio seleziona i record sui dipendenti dalle tabelle EMPLOYEES e EMPLOYEE_DEPARTMENT. Se l'azione ha esito positivo, il parametro di risposta connectorOutputPayload dell'attività del connettore avrà il risultato della query impostato.

Esempio: eseguire una query con parametri

  1. Nella finestra di dialogo Configura l'attività del connettore, seleziona Azioni.
  2. Seleziona l'azione Esegui query personalizzata e fai clic su Fine.
  3. Nella sezione Input attività dell'attività Connettori, imposta i seguenti valori per il campo:
    1. Timeout dopo: 10
    2. Numero massimo di righe: 3
  4. Fai clic su + Aggiungi nome parametro per inserire i seguenti valori:
    1. Tipo: VARCHAR
    2. Valore: John
  5. Fai clic su Modifica query personalizzata. Viene visualizzata la finestra di dialogo Query personalizzata.
  6. Nella finestra di dialogo Query personalizzata, inserisci la seguente query SQL e fai clic su Salva: 
      Select C.ID,C.NAME,C.CITY,C.O_DATE,E.EMPLOYEE_ID
  FROM customqueries C,Employees E
  WHERE C.ID=E.Employee_id and C.NAME=?

    7. In questo esempio vengono selezionati i record dei dipendenti, in cui il nome del dipendente è John. Nota che il nome del dipendente è parametrizzato. Se l'azione ha esito positivo, il parametro di risposta connectorOutputPayload dell'attività del connettore avrà un valore simile al seguente:

    [{
"NAME": "John",
"O_DATE": "2023-06-01 00:00:00.0",
"EMPLOYEE_ID": 1.0
}, {
"NAME": "John",
"O_DATE": "2021-07-01 00:00:00.0",
"EMPLOYEE_ID": 3.0
}, {
"NAME": "John",
"O_DATE": "2022-09-01 00:00:00.0",
"EMPLOYEE_ID": 4.0
}]

Esempio: inserire un record utilizzando un valore sequenza

  1. Nella finestra di dialogo Configura l'attività del connettore, seleziona Azioni.
  2. Seleziona l'azione Esegui query personalizzata e fai clic su Fine.
  3. Nella finestra di dialogo Query personalizzata, inserisci la seguente query SQL e fai clic su Salva: 
      INSERT INTO AUTHOR(id,title) VALUES(author_table_id_seq.NEXTVAL,'Sample_book_title')

    4. Questo esempio inserisce un record nella tabella AUTHOR utilizzando un oggetto sequenza author_table_id_seq esistente. Se l'azione ha esito positivo, il parametro di risposta connectorOutputPayload dell'attività del connettore avrà un valore simile al seguente:

    [{
}]

Esempio: eseguire una query con una funzione aggregata

  1. Nella finestra di dialogo Configura l'attività del connettore, seleziona Azioni.
  2. Seleziona l'azione Esegui query personalizzata e fai clic su Fine.
  3. Nella finestra di dialogo Query personalizzata, inserisci la seguente query SQL e fai clic su Salva: 
      SELECT SUM(SALARY) as Total FROM EMPLOYEES

    4. Questo esempio calcola il valore aggregato degli stipendi nella tabella EMPLOYEES. Se l'azione ha esito positivo, il parametro di risposta connectorOutputPayload dell'attività del connettore avrà un valore simile al seguente:

    [{
"TOTAL": 13000.0
}]

Esempio: creare una nuova tabella

  1. Nella finestra di dialogo Configura l'attività del connettore, seleziona Azioni.
  2. Seleziona l'azione Esegui query personalizzata e fai clic su Fine.
  3. Nella finestra di dialogo Query personalizzata, inserisci la seguente query SQL e fai clic su Salva: 
        CREATE TABLE TEST1 (ID INT, NAME VARCHAR(40),DEPT VARCHAR(20),CITY VARCHAR(10))

    4. In questo esempio viene creata la tabella TEST1. Se l'azione ha esito positivo, il parametro di risposta connectorOutputPayload dell'attività del connettore avrà un valore simile al seguente:

    [{
}]

Esempi di operazioni sull'entità

Esempio: indica tutti i dipendenti

In questo esempio sono elencati tutti i dipendenti nell'entità Employee.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Employee dall'elenco Entity.
  3. Seleziona l'operazione List, quindi fai clic su Fine.
  4. Facoltativamente, nella sezione Input attività dell'attività Connettori, puoi filtrare il set di risultati specificando una clausola di filtro.

Esempio: recuperare i dettagli del dipendente

Questo esempio prende i dettagli del dipendente il cui ID è 45, dall'entità Employee.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Employee dall'elenco Entity.
  3. Seleziona l'operazione Get, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su EntityId e inserisci 45 nel campo Valore predefinito.

    Qui, 45 è il valore della chiave primaria dell'entità Employee.

Esempio: creare un record di dipendente

In questo esempio viene aggiunto un nuovo record relativo ai dipendenti nell'entità Employee.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Employee dall'elenco Entity.
  3. Seleziona l'operazione Create, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su connectorInputPayload e inserisci un valore simile al seguente nel campo Default Value: 
    {
"EMPLOYEE_ID": 69.0,
"EMPLOYEE_NAME": "John",
"CITY": "Bangalore"
}

    Se l'integrazione ha esito positivo, il campo connectorOutputPayload dell'attività del connettore avrà un valore simile al seguente:

     {
"ROWID": "AAAoU0AABAAAc3hAAF"
}

Esempio: aggiornamento di un record di dipendenti

Questo esempio aggiorna il record del dipendente il cui ID è 69 nell'entità Employee.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Employee dall'elenco Entity.
  3. Seleziona l'operazione Update, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su connectorInputPayload e inserisci un valore simile al seguente nel campo Default Value: 
    {
"EMPLOYEE_NAME": "John",
"CITY": "Mumbai"
}
  5. Fai clic su entityId, quindi inserisci 69 nel campo Default Value (Valore predefinito).

    In alternativa, anziché specificare entityId, puoi anche impostare filterClause su 69.

    Se l'integrazione ha esito positivo, il campo connectorOutputPayload dell'attività del connettore avrà un valore simile al seguente:

    {
}

Esempio: eliminare un record di dipendenti

Questo esempio elimina il record del dipendente il cui ID è 35 nell'entità Employee.

  1. Nella finestra di dialogo Configure connector task, fai clic su Entities.
  2. Seleziona Employee dall'elenco Entity.
  3. Seleziona l'operazione Delete, quindi fai clic su Fine.
  4. Nella sezione Input attività dell'attività Connettori, fai clic su entityId, quindi inserisci 35 nel campo Valore predefinito.

Utilizzare Terraform per creare connessioni

Puoi utilizzare la risorsa Terraform per creare una nuova connessione.

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

Per visualizzare un modello Terraform di esempio per la creazione delle connessioni, guarda il modello di esempio.

Quando crei questa connessione utilizzando Terraform, devi impostare le seguenti variabili nel file di configurazione Terraform:

Nome parametro Tipo di dati Obbligatorio Descrizione
service_name STRING False Il nome del servizio del database Oracle.
data_source STRING False Nome Oracle Net Services, descrittore di connessione (noto anche come stringa di connessione TNS) o una denominazione di connessione semplice che identifica il database a cui connettersi.
include_synonyms BOOLEANO False Esegui query nei metadati per trovare sinonimi e rendili disponibili come entità. L'impostazione della proprietà su false può aumentare le prestazioni dei metadati.
abandoned_connection_timeout INTEGER False Il timeout della connessione abbandonata (in secondi) determina per quanto tempo una connessione presa in prestito può rimanere inutilizzata prima di essere considerata abbandonata e recuperata dal pool di connessioni.
inactive_connection_timeout INTEGER False Il timeout di connessione non attiva (in secondi) determina per quanto tempo una connessione disponibile rimane nel pool di connessioni prima di essere rimossa dal pool.
max_connection_reuse_time INTEGER False Il tempo massimo di riutilizzo della connessione (in secondi) specifica il tempo massimo per cui una connessione può essere potenzialmente riutilizzata, dopodiché il pool rimuove e chiude una connessione.
ttl_connection_timeout INTEGER False Tempo massimo (in secondi) durante il quale una connessione può rimanere in uso.
browsable_schemas STRING False Schemi separati da virgole (ad es. SchemaA, SchemaB) da utilizzare per il recupero di entità e azioni per la connessione. Utilizza lo schema dell'utente per impostazione predefinita

Utilizza la connessione Oracle DB in un'integrazione

Dopo aver creato la connessione, diventa disponibile sia in Apigee Integration che in Application Integration. Puoi usare la connessione in un'integrazione tramite l'attività Connettori.

  • Per capire come creare e utilizzare l'attività Connettori in Apigee Integration, consulta Attività Connettori.
  • Per capire come creare e utilizzare l'attività Connettori in Application Integration, consulta Attività Connettori.

Ricevi assistenza dalla community Google Cloud

Puoi pubblicare le tue domande e discutere di questo connettore nella community Google Cloud sui forum Cloud.

Passaggi successivi