Oracle DB (versi 2)

Konektor Oracle DB memungkinkan Anda terhubung ke instance database Oracle (versi 11.2 atau yang lebih baru) dan melakukan operasi database yang didukung.

Sebelum memulai

Sebelum menggunakan konektor Oracle DB, lakukan tugas berikut:

  • Di project Google Cloud Anda:
    • Pastikan konektivitas jaringan sudah disiapkan. Untuk mengetahui informasi tentang pola jaringan, lihat Konektivitas jaringan.
    • Berikan peran IAM roles/connectors.admin kepada pengguna yang mengonfigurasi konektor.
    • Berikan peran IAM berikut ke akun layanan yang ingin Anda gunakan untuk konektor:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      Akun layanan adalah jenis Akun Google khusus yang dimaksudkan untuk mewakili pengguna non-manusia yang perlu diautentikasi dan diberi otorisasi untuk mengakses data di Google API. Jika tidak memiliki akun layanan, Anda harus membuat akun layanan. Untuk informasi selengkapnya, lihat Membuat akun layanan.

    • Aktifkan layanan berikut:
      • secretmanager.googleapis.com (Secret Manager API)
      • connectors.googleapis.com (Connectors API)

      Untuk memahami cara mengaktifkan layanan, lihat Mengaktifkan layanan.

    Jika layanan atau izin ini belum diaktifkan untuk project Anda sebelumnya, Anda akan diminta untuk mengaktifkannya saat mengonfigurasi konektor.

Mengonfigurasi konektor

Untuk mengonfigurasi konektor, Anda harus membuat koneksi ke sumber data (sistem backend). Koneksi bersifat khusus untuk sumber data. Artinya, jika memiliki banyak sumber data, Anda harus membuat koneksi terpisah untuk setiap sumber data. Untuk membuat koneksi, lakukan langkah-langkah berikut:

  1. Di konsol Cloud, buka halaman Konektor Integrasi > Koneksi, lalu pilih atau buat project Google Cloud.

    Buka halaman Koneksi

  2. Klik + Buat baru untuk membuka halaman Buat Koneksi.
  3. Di bagian Location, pilih lokasi untuk koneksi.
    1. Region: Pilih lokasi dari menu drop-down.

      Untuk mengetahui daftar semua region yang didukung, lihat Lokasi.

    2. Klik Berikutnya.
  4. Di bagian Connection Details, selesaikan tindakan berikut:
    1. Konektor: Pilih Oracle DB dari menu drop-down Konektor yang tersedia.
    2. Versi konektor: Pilih versi 2 dari menu drop-down versi yang tersedia.
    3. Di kolom Connection Name, masukkan nama untuk instance Connection.

      Nama koneksi harus memenuhi kriteria berikut:

      • Nama koneksi dapat menggunakan huruf, angka, atau tanda hubung.
      • Huruf harus berupa huruf kecil.
      • Nama koneksi harus diawali dengan huruf dan diakhiri dengan huruf atau angka.
      • Nama koneksi tidak boleh melebihi 49 karakter.
    4. Secara opsional, masukkan Description untuk instance koneksi.
    5. Secara opsional, aktifkan Cloud Logging, lalu pilih level log. Secara default, level log ditetapkan ke Error.
    6. Secara opsional, pilih Aktifkan Cloud Logging untuk mengaktifkan logging cloud.
    7. Service Account: Pilih akun layanan yang memiliki peran yang diperlukan.
    8. Secara opsional, konfigurasikan Setelan node koneksi:

      • Jumlah node minimum: Masukkan jumlah minimum node koneksi.
      • Maximum number of nodes: Masukkan jumlah maksimum node koneksi.

      Node adalah unit (atau replika) koneksi yang memproses transaksi. Semakin banyak node yang diperlukan untuk memproses lebih banyak transaksi untuk koneksi, dan sebaliknya, semakin sedikit node yang diperlukan untuk memproses lebih sedikit transaksi. Untuk memahami pengaruh node terhadap harga konektor, lihat Harga untuk node koneksi. Jika Anda tidak memasukkan nilai apa pun, secara default, node minimum ditetapkan ke 2 (untuk ketersediaan yang lebih baik) dan node maksimum ditetapkan ke 50.

    9. Berdasarkan apakah koneksi DB Oracle Anda menggunakan koneksi berbasis server atau konektivitas TNS, tentukan ServiceName atau DataSource (string koneksi TNS). Jika Anda menentukan keduanya, DataSource akan digunakan.
      • ServiceName: Jika Anda menggunakan autentikasi berbasis server, tentukan nama layanan beserta detail tujuan.
      • DataSource: Jika Anda menggunakan konektivitas TNS, tentukan Nama Layanan Net Oracle, Deskripsi Koneksi (juga dikenal sebagai string koneksi TNS), atau penamaan koneksi mudah yang mengidentifikasi database yang akan dihubungkan. Anda tidak perlu menentukan detail tujuan. Gunakan format berikut untuk menentukan string koneksi TNS: (DESCRIPTION=(ADDRESS=(protocol_address_information))(CONNECT_DATA= (SERVICE_NAME=service_name))).
    10. Secara opsional, pilih Sertakan Sinonim.
    11. Waktu Tunggu Koneksi yang Ditinggalkan: Masukkan nilai waktu tunggu (dalam detik) yang menentukan berapa lama koneksi yang dipinjam dapat tetap tidak digunakan sebelum dianggap ditinggalkan.
    12. Waktu Tunggu Koneksi Tidak Aktif: Masukkan nilai waktu tunggu koneksi (dalam detik).
    13. Max Connection Reuse Time: Masukkan waktu penggunaan kembali koneksi (dalam detik).
    14. TTL Connection Timeout: Masukkan waktu maksimum (dalam detik) koneksi dapat tetap digunakan.
    15. Skema yang Dapat Di-brows: Masukkan nama skema yang dipisahkan koma yang akan digunakan saat mengambil entitas dan tindakan. Contoh, schemaA, schemaB, schemaC.
    16. Secara opsional, klik + TAMBAHKAN LABEL untuk menambahkan label ke Koneksi dalam bentuk pasangan kunci/nilai.
    17. Klik NEXT.
  5. Di bagian Destinations, masukkan detail host jarak jauh (sistem backend) yang ingin Anda hubungkan.
    1. Jenis Tujuan: Pilih Jenis Tujuan.
      • Pilih Host address dari daftar untuk menentukan nama host atau alamat IP tujuan.
      • Jika Anda ingin membuat koneksi pribadi ke sistem backend, pilih Endpoint attachment dari daftar, lalu pilih lampiran endpoint yang diperlukan dari daftar Endpoint Attachment.

      Jika ingin membuat koneksi publik ke sistem backend dengan keamanan tambahan, Anda dapat mempertimbangkan untuk mengonfigurasi alamat IP keluar statis untuk koneksi, lalu mengonfigurasi aturan firewall untuk hanya mengizinkan alamat IP statis tertentu.

      Untuk memasukkan tujuan tambahan, klik +TAMBAHKAN TUJUAN.

    2. Klik NEXT.
  6. Di bagian Authentication, masukkan detail autentikasi.
    1. Pilih Jenis autentikasi dan masukkan detail yang relevan.

      Jenis autentikasi berikut didukung oleh koneksi DB Oracle:

      • Nama pengguna dan sandi
    2. Untuk memahami cara mengonfigurasi jenis autentikasi ini, lihat Mengonfigurasi autentikasi.

    3. Klik NEXT.
  7. Tinjau: Tinjau detail koneksi dan autentikasi Anda.
  8. Klik Create.

Mengonfigurasi autentikasi

Masukkan detail berdasarkan autentikasi yang ingin Anda gunakan.

  • Nama pengguna dan sandi
    • Nama pengguna: Nama pengguna akun Oracle yang digunakan untuk autentikasi
    • Sandi: Secret Manager Secret yang berisi sandi yang terkait dengan nama pengguna akun Oracle.

Entity, operasi, dan tindakan

Semua Konektor Integrasi menyediakan lapisan abstraksi untuk objek aplikasi yang terhubung. Anda hanya dapat mengakses objek aplikasi melalui abstraksi ini. Abstraksi ditampilkan kepada Anda sebagai entitas, operasi, dan tindakan.

  • Entity: Entity dapat dianggap sebagai objek, atau kumpulan properti, dalam aplikasi atau layanan yang terhubung. Definisi entitas berbeda dari konektor ke konektor. Misalnya, dalam konektor database, tabel adalah entitas, dalam konektor server file, folder adalah entitas, dan dalam konektor sistem pesan, antrean adalah entitas.

    Namun, mungkin konektor tidak mendukung atau memiliki entity apa pun, dalam hal ini, daftar Entities akan kosong.

  • Operasi: Operasi adalah aktivitas yang dapat Anda lakukan pada entity. Anda dapat melakukan salah satu operasi berikut pada entitas:

    Memilih entitas dari daftar yang tersedia akan menghasilkan daftar operasi yang tersedia untuk entitas tersebut. Untuk deskripsi mendetail tentang operasi, lihat operasi entity tugas Konektor. Namun, jika konektor tidak mendukung operasi entitas apa pun, operasi yang tidak didukung tersebut tidak akan tercantum dalam daftar Operations.

  • Tindakan: Tindakan adalah fungsi kelas satu yang tersedia untuk integrasi melalui antarmuka konektor. Tindakan memungkinkan Anda membuat perubahan pada satu atau beberapa entitas, dan bervariasi dari satu konektor ke konektor lainnya. Biasanya, tindakan akan memiliki beberapa parameter input, dan parameter output. Namun, konektor mungkin tidak mendukung tindakan apa pun, dalam hal ini daftar Actions akan kosong.

Batasan sistem

Konektor Oracle DB dapat memproses maksimum 70 transaksi per detik, per node, dan mencegah transaksi apa pun yang melebihi batas ini. Secara default, Konektor Integrasi mengalokasikan 2 node (untuk ketersediaan yang lebih baik) untuk koneksi.

Untuk mengetahui informasi tentang batas yang berlaku untuk Konektor Integrasi, lihat Batas.

Jenis data yang didukung

Berikut adalah jenis data yang didukung untuk konektor ini:

  • BIGINT
  • BINARY
  • BIT
  • BOOLEAN
  • CHAR
  • DATE
  • DECIMAL
  • DOUBLE
  • FLOAT
  • INTEGER
  • LONGN VARCHAR
  • LONG VARCHAR
  • NCHAR
  • NUMERIC
  • NVARCHAR
  • REAL
  • SMALL INT
  • WAKTU
  • TIMESTAMP
  • TINY INT
  • VARBINARY
  • VARCHAR

Tindakan

Konektor Oracle DB memungkinkan Anda mengeksekusi prosedur tersimpan, fungsi, dan kueri SQL kustom dalam format yang didukung oleh database Oracle. Untuk menjalankan kueri SQL kustom, konektor menyediakan tindakan Execute custom query.

Untuk membuat kueri kustom, ikuti langkah-langkah berikut:

  1. Ikuti petunjuk mendetail untuk menambahkan tugas konektor.
  2. Saat Anda mengonfigurasi tugas konektor, pilih Tindakan pada jenis tindakan yang ingin Anda lakukan.
  3. Dalam daftar Action, pilih Execute custom query, lalu klik Done.

    gambar yang menampilkan execute-custom-query-action gambar yang menampilkan execute-custom-query-action

  4. Luaskan bagian Task input, lalu lakukan hal berikut:
    1. Di kolom Waktu tunggu setelah, masukkan jumlah detik untuk menunggu hingga kueri dieksekusi.

      Nilai default: 180 detik.

    2. Di kolom Jumlah baris maksimum, masukkan jumlah baris maksimum yang akan ditampilkan dari database.

      Nilai default: 25.

    3. Untuk memperbarui kueri kustom, klik Edit Skrip Kustom. Dialog Script editor akan terbuka.

      gambar yang menampilkan custom-sql-query gambar yang menampilkan custom-sql-query

    4. Di dialog Editor skrip, masukkan kueri SQL, lalu klik Simpan.

      Anda dapat menggunakan tanda tanya (?) dalam pernyataan SQL untuk mewakili satu parameter yang harus ditentukan dalam daftar parameter kueri. Misalnya, kueri SQL berikut memilih semua baris dari tabel Employees yang cocok dengan nilai yang ditentukan untuk kolom LastName:

      SELECT * FROM Employees where LastName=?

    5. Jika telah menggunakan tanda tanya dalam kueri SQL, Anda harus menambahkan parameter dengan mengklik + Tambahkan Nama Parameter untuk setiap tanda tanya. Saat menjalankan integrasi, parameter ini akan mengganti tanda tanya (?) dalam kueri SQL secara berurutan. Misalnya, jika telah menambahkan tiga tanda tanya (?), Anda harus menambahkan tiga parameter dalam urutan.

      gambar yang menampilkan add-query-param gambar yang menampilkan add-query-param

      Untuk menambahkan parameter kueri, lakukan tindakan berikut:

      1. Dari daftar Type, pilih jenis data parameter.
      2. Di kolom Value, masukkan nilai parameter.
      3. Untuk menambahkan beberapa parameter, klik + Tambahkan Parameter Kueri.

Untuk memahami cara menggunakan tindakan kueri kustom, lihat Contoh tindakan.

Contoh tindakan

Bagian ini menjelaskan cara melakukan beberapa tindakan di konektor ini.

Contoh - Menjalankan grup menurut kueri

  1. Pada dialog Configure connector task, pilih Actions.
  2. Pilih tindakan Execute custom query, lalu klik Done.
  3. Di bagian Task Input pada tugas Connectors, klik Edit Custom Query. Dialog Custom query akan terbuka.
  4. Pada dialog Kueri kustom, masukkan kueri SQL berikut, lalu klik Simpan:
          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
        

    Contoh ini memilih kumpulan data karyawan dari tabel EMPLOYEES dan EMPLOYEE_DEPARTMENT. Jika tindakan berhasil, parameter respons connectorOutputPayload tugas konektor Anda akan memiliki kumpulan hasil kueri.

Contoh - Menjalankan kueri berparameter

  1. Pada dialog Configure connector task, pilih Actions.
  2. Pilih tindakan Execute custom query, lalu klik Done.
  3. Di bagian Task Input pada tugas Connectors, tetapkan nilai berikut untuk kolom:
    1. Waktu tunggu habis setelah: 10
    2. Jumlah maksimum baris: 3
  4. Klik +Tambahkan Nama parameter untuk memasukkan nilai berikut:
    1. Jenis: VARCHAR
    2. Nilai: John
  5. Klik Edit Kueri Kustom. Dialog Custom query akan terbuka.
  6. Pada dialog Kueri kustom, masukkan kueri SQL berikut, lalu klik Simpan:
      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. Contoh ini memilih data karyawan dengan nama karyawan John. Perhatikan bahwa nama karyawan diparameterisasi. Jika tindakan berhasil, parameter respons connectorOutputPayload tugas konektor Anda akan memiliki nilai yang mirip dengan berikut:

    [{
    "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
    }]

Contoh - Menyisipkan data menggunakan nilai urutan

  1. Pada dialog Configure connector task, pilih Actions.
  2. Pilih tindakan Execute custom query, lalu klik Done.
  3. Pada dialog Kueri kustom, masukkan kueri SQL berikut, lalu klik Simpan:
      INSERT INTO AUTHOR(id,title) VALUES(author_table_id_seq.NEXTVAL,'Sample_book_title')
  4. Contoh ini menyisipkan data dalam tabel AUTHOR, dengan menggunakan objek urutan author_table_id_seq yang ada. Jika tindakan berhasil, parameter respons connectorOutputPayload tugas konektor Anda akan memiliki nilai yang mirip dengan berikut:

    [{
    }]

Contoh - Menjalankan kueri dengan fungsi agregat

  1. Pada dialog Configure connector task, pilih Actions.
  2. Pilih tindakan Execute custom query, lalu klik Done.
  3. Pada dialog Kueri kustom, masukkan kueri SQL berikut, lalu klik Simpan:
      SELECT SUM(SALARY) as Total FROM EMPLOYEES
      
  4. Contoh ini menghitung nilai gabungan gaji di tabel EMPLOYEES. Jika tindakan berhasil, parameter respons connectorOutputPayload tugas konektor Anda akan memiliki nilai yang mirip dengan berikut:

    [{
    "TOTAL": 13000.0
    }]  
      

Contoh - Membuat tabel baru

  1. Pada dialog Configure connector task, pilih Actions.
  2. Pilih tindakan Execute custom query, lalu klik Done.
  3. Pada dialog Kueri kustom, masukkan kueri SQL berikut, lalu klik Simpan:
        CREATE TABLE TEST1 (ID INT, NAME VARCHAR(40),DEPT VARCHAR(20),CITY VARCHAR(10))
     
  4. Contoh ini membuat tabel TEST1. Jika tindakan berhasil, parameter respons connectorOutputPayload tugas konektor Anda akan memiliki nilai yang mirip dengan berikut:

    [{
    }]

Contoh operasi entity

Contoh - Mencantumkan semua karyawan

Contoh ini mencantumkan semua karyawan dalam entitas Employee.

  1. Pada dialog Configure connector task, klik Entities.
  2. Pilih Employee dari daftar Entity.
  3. Pilih operasi List, lalu klik Selesai.
  4. Secara opsional, di bagian Input Tugas pada tugas Konektor, Anda dapat memfilter set hasil dengan menentukan klausa filter.

Contoh - Mendapatkan detail karyawan

Contoh ini mendapatkan detail karyawan yang ID-nya adalah 45, dari entity Employee.

  1. Pada dialog Configure connector task, klik Entities.
  2. Pilih Employee dari daftar Entity.
  3. Pilih operasi Get, lalu klik Selesai.
  4. Di bagian Task Input pada tugas Connectors, klik EntityId, lalu masukkan 45 di kolom Default Value.

    Di sini, 45 adalah nilai kunci utama entity Employee.

Contoh - Membuat data karyawan

Contoh ini menambahkan data karyawan baru di entitas Employee.

  1. Pada dialog Configure connector task, klik Entities.
  2. Pilih Employee dari daftar Entity.
  3. Pilih operasi Create, lalu klik Done.
  4. Di bagian Task Input pada tugas Connectors, klik connectorInputPayload, lalu masukkan nilai yang mirip dengan berikut di kolom Default Value:
    {
    "EMPLOYEE_ID": 69.0,
    "EMPLOYEE_NAME": "John",
    "CITY": "Bangalore"
    }

    Jika integrasi berhasil, kolom connectorOutputPayload tugas konektor Anda akan memiliki nilai yang mirip dengan berikut ini:

     {
    "ROWID": "AAAoU0AABAAAc3hAAF"
    }

Contoh - Memperbarui data karyawan

Contoh ini memperbarui data karyawan yang ID-nya adalah 69 di entitas Employee.

  1. Pada dialog Configure connector task, klik Entities.
  2. Pilih Employee dari daftar Entity.
  3. Pilih operasi Update, lalu klik Done.
  4. Di bagian Task Input pada tugas Connectors, klik connectorInputPayload, lalu masukkan nilai yang mirip dengan berikut di kolom Default Value:
    {
    "EMPLOYEE_NAME": "John",
    "CITY": "Mumbai"
    }
  5. Klik entityId, lalu masukkan 69 di kolom Default Value.

    Atau, alih-alih menentukan entityId, Anda juga dapat menetapkan filterClause ke 69.

    Jika integrasi berhasil, kolom connectorOutputPayload tugas konektor Anda akan memiliki nilai yang mirip dengan berikut ini:

    {
    }

Contoh - Menghapus data karyawan

Contoh ini menghapus data karyawan yang ID-nya adalah 35 di entitas Employee.

  1. Pada dialog Configure connector task, klik Entities.
  2. Pilih Employee dari daftar Entity.
  3. Pilih operasi Delete, lalu klik Done.
  4. Di bagian Task Input pada tugas Connectors, klik entityId, lalu masukkan 35 di kolom Default Value.

Menggunakan terraform untuk membuat koneksi

Anda dapat menggunakan resource Terraform untuk membuat koneksi baru.

Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform.

Untuk melihat contoh template terraform untuk pembuatan koneksi, lihat contoh template.

Saat membuat koneksi ini menggunakan Terraform, Anda harus menetapkan variabel berikut dalam file konfigurasi Terraform:

Nama parameter Jenis data Wajib Deskripsi
service_name STRING Salah Nama layanan database Oracle.
data_source STRING Salah Nama Layanan Net Oracle, Deskripsi Koneksi (juga dikenal sebagai String Koneksi TNS), atau penamaan koneksi mudah yang mengidentifikasi database yang akan dihubungkan.
include_synonyms BOOLEAN Salah Buat kueri metadata untuk sinonim dan sediakan sebagai entity. Menetapkan properti ke salah dapat meningkatkan performa metadata.
abandoned_connection_timeout INTEGER Salah Waktu tunggu koneksi yang diabaikan (dalam detik) menentukan berapa lama koneksi yang dipinjam dapat tetap tidak digunakan sebelum dianggap sebagai diabaikan dan diambil kembali oleh kumpulan koneksi.
inactive_connection_timeout INTEGER Salah Waktu tunggu koneksi tidak aktif (dalam detik) menentukan berapa lama koneksi yang tersedia tetap berada di kumpulan koneksi sebelum dihapus dari kumpulan.
max_connection_reuse_time INTEGER Salah Waktu penggunaan kembali koneksi maksimum (dalam detik) menentukan waktu maksimum koneksi yang berpotensi dapat digunakan kembali, setelah itu kumpulan akan menghapus dan menutup koneksi.
ttl_connection_timeout INTEGER Salah Waktu maksimum (dalam detik) koneksi dapat tetap digunakan.
browsable_schemas STRING Salah Skema yang dipisahkan koma (Misalnya, SchemaA, SchemaB) yang akan digunakan saat mengambil entity dan tindakan untuk koneksi. Menggunakan skema pengguna secara default

Menggunakan koneksi DB Oracle dalam integrasi

Setelah Anda membuat koneksi, koneksi tersebut akan tersedia di Integration Apigee dan Integration Aplikasi. Anda dapat menggunakan koneksi dalam integrasi melalui tugas Konektor.

  • Untuk memahami cara membuat dan menggunakan tugas Konektor di Apigee Integration, lihat Tugas konektor.
  • Untuk memahami cara membuat dan menggunakan tugas Konektor di Integrasi Aplikasi, lihat Tugas konektor.

Mendapatkan bantuan dari komunitas Google Cloud

Anda dapat memposting pertanyaan dan mendiskusikan konektor ini di komunitas Google Cloud di Cloud Forums.

Langkah selanjutnya