Lihat konektor yang didukung untuk Integration Aplikasi.

Tugas konektor

Tugas Konektor memungkinkan Anda terhubung dengan cepat dan aman ke berbagai layanan Google Cloud dan aplikasi bisnis lainnya dari integrasi Anda menggunakan konektor siap pakai yang tersedia di Konektor Integrasi.

Untuk mengetahui daftar semua konektor yang didukung untuk Integrasi Aplikasi, lihat Referensi konektor.

Penting: Konektor Integrasi adalah komponen Google Cloud yang dapat ditagih. Untuk mengetahui informasi tentang biaya dan tagihan penggunaan Integration Connectors, lihat Harga Integration Connectors.

Sebelum memulai

• Pastikan Anda memiliki peran IAM Connectors Admin (roles/connectors.admin) yang diberikan di project Google Cloud Anda. Untuk mengetahui informasi tentang cara memberikan peran, lihat Mengelola akses.
• Pelajari konsep umum Konektor Integrasi.
• Untuk terhubung ke layanan Google Cloud dan aplikasi bisnis lainnya menggunakan konektor, pastikan Anda telah melampirkan akun layanan yang dikelola pengguna ke integrasi Anda. Jika integrasi Anda tidak memiliki akun layanan yang dikelola pengguna yang dikonfigurasi, secara default akun layanan default (service-PROJECT_NUMBER@gcp-sa-integrations.) akan digunakan untuk autentikasi.
• Pastikan akun layanan Anda memiliki peran IAM yang diperlukan. Untuk informasi tentang cara memberikan peran ke akun layanan, lihat Mengelola akses ke akun layanan.

Menambahkan tugas Konektor

Untuk menambahkan tugas Konektor dalam integrasi Anda, lakukan hal berikut:

1. Di konsol Google Cloud, buka halaman Integrasi Aplikasi.

   Buka Application Integration

2. Di menu navigasi, klik Integrations.

   Halaman Integrasi akan muncul yang mencantumkan semua integrasi yang tersedia di project Google Cloud.

3. Pilih integrasi yang ada atau klik Buat integrasi untuk membuat integrasi baru.

   Jika Anda membuat integrasi baru:

   1. Masukkan nama dan deskripsi di panel Buat Integrasi.
   2. Pilih region untuk integrasi.
      Catatan: Drop-down Regions hanya mencantumkan region yang disediakan di project Google Cloud Anda. Untuk menyediakan wilayah baru, klik Aktifkan Wilayah. Lihat Mengaktifkan region baru untuk informasi selengkapnya.
   3. Pilih akun layanan untuk integrasi. Anda dapat mengubah atau memperbarui detail akun layanan integrasi kapan saja dari panel Ringkasan integrasi di toolbar integrasi.
      Catatan: Opsi untuk memilih akun layanan hanya ditampilkan jika Anda telah mengaktifkan tata kelola integrasi untuk wilayah yang dipilih.
   4. Klik Create.

   Tindakan ini akan membuka integrasi di editor integrasi.

4. Di menu navigasi editor integrasi, klik Tugas untuk melihat daftar tugas dan konektor yang tersedia.



5. Jika Anda ingin mengonfigurasi koneksi baru, klik dan tempatkan elemen Konektor di editor integrasi. Kemudian, klik Konfigurasi konektor untuk mengonfigurasi koneksi.

   

6. Jika Anda sudah memiliki koneksi, klik tab Konektor untuk melihat koneksi yang baru dibuat. Anda juga dapat menelusuri konektor, koneksi, atau tugas dengan memasukkan namanya di kolom Telusuri.

   

7. Klik dan tempatkan elemen Konektor yang dikonfigurasi di editor integrasi. Untuk mengetahui informasi tentang cara mengonfigurasi tugas konektor, lihat Mengonfigurasi tugas Konektor.

Mengonfigurasi tugas Konektor

Untuk mengonfigurasi tugas Konektor, lakukan hal berikut:

Catatan: Detail konfigurasi seperti autentikasi akan bervariasi bergantung pada jenis koneksi.

1. Klik elemen tugas Connectors di desainer untuk melihat panel konfigurasi tugas Connectors.

   Atau, klik untuk mengganti nama tugas.

2. Klik Configure connector.
3. Anda dapat memilih koneksi yang ada di wilayah tersebut atau membuat koneksi baru. Untuk mengonfigurasi koneksi yang ada, selesaikan langkah-langkah berikut di halaman Connectors Task Editor.

   Gambar berikut menunjukkan contoh tata letak halaman Editor Tugas Konektor.

1. Di bagian Select connection, pilih region koneksi.
2. Pilih koneksi yang ada dari daftar koneksi yang tersedia di region yang dipilih.
3. Klik Berikutnya.
4. Dari daftar Jenis, pilih Entity atau Actions.
   • Jika Anda memilih Entities, daftar entitas yang didukung untuk koneksi akan ditampilkan di bagian Set entities/actions. Pilih entity, diikuti dengan Operasi yang ingin Anda lakukan pada entity tersebut.
   • Jika Anda memilih Actions, daftar tindakan yang didukung untuk koneksi akan ditampilkan di kolom Set entities/actions. Pilih tindakan untuk koneksi.
   Entitas dan tindakan yang didukung didasarkan pada jenis konektor. Untuk mengetahui daftar semua konektor yang didukung untuk Integrasi Aplikasi, lihat Referensi konektor. Untuk melihat tindakan dan entitas yang didukung untuk konektor, lihat dokumentasi konektor tertentu.

   Jika konektor mendukung kueri SQL kustom, Anda dapat memilih opsi Execute custom query dari daftar Actions. Untuk informasi tentang cara menambahkan kueri SQL kustom untuk konektor Anda, lihat Tindakan: Menjalankan kueri SQL kustom.

   Catatan: Tidak semua jenis koneksi mendukung Entity atau Action. Jika jenis koneksi tidak mendukung tindakan atau entity apa pun, daftar Entity dan Actions yang sesuai akan kosong. Untuk mengetahui informasi selengkapnya tentang entity dan tindakan, lihat Entity, operasi, dan tindakan.
5. Klik Done untuk menyelesaikan konfigurasi koneksi dan menutup panel.

Mengonfigurasi variabel input dan output tugas

Panel konfigurasi tugas Konektor menampilkan variabel Input Tugas dan Output Tugas yang otomatis dibuat berdasarkan Entity and Operation atau Action yang dipilih di dialog Configure connector task. Variabel ini dapat dikonfigurasi dan dapat diakses sebagai input untuk tugas saat ini atau sebagai output untuk tugas berikutnya, atau kondisional dalam integrasi saat ini.

Untuk mengonfigurasi variabel Task Input atau Task Output, klik variabel masing-masing untuk membuka panel Configure Variable dan lakukan langkah-langkah berikut:

1. Masukkan nilai variabel di kolom Default Value.
2. (Opsional) Pilih Gunakan sebagai input untuk integrasi atau Gunakan sebagai output untuk integrasi.
3. Klik Simpan.

Untuk informasi selengkapnya tentang parameter input dan output tugas Konektor, lihat Operasi entity.

Operasi dan tindakan entity

Anda dapat melakukan operasi CRUD (Create, Read, Update, Delete) pada entity konektor. Setiap operasi entity ini memiliki kumpulan parameter input dan output yang berbeda. Tabel berikut mencantumkan parameter input dan output dari berbagai operasi entity.

Nama operasi	Parameter input	Parameter output
Daftar	listEntitiesPageSize listEntitiesPageToken listEntitiesSortByColumns filterClause	connectorOutputPayload listEntitiesNextPageToken
Dapatkan	entityId	connectorOutputPayload
	Catatan: Anda hanya dapat menggunakan operasi Get untuk mengambil satu kumpulan data dari tabel yang memiliki kunci utama. Atau, Anda dapat menggunakan operasi List dengan filterClause.
Buat	connectorInputPayload	connectorOutputPayload
Perbarui	connectorInputPayload entityId filterClause	connectorOutputPayload
Hapus	entityId filterClause	T/A

Parameter input

Tabel berikut menjelaskan parameter input untuk berbagai operasi entity.

Nama parameter	Jenis data	Deskripsi
entityId	String	ID unik baris yang ingin Anda akses. Biasanya, entityId adalah nilai kunci utama tabel atau set data. Jika Anda menentukan nilai untuk entityId dan tabel atau set data tidak memiliki kolom kunci utama, integrasi akan melaporkan error runtime dan tugas Konektor akan gagal. Misalnya, untuk mendapatkan baris tertentu dari tabel MySQL, entityId adalah nilai kunci utama dalam tabel. Catatan: entityId tidak wajib untuk BigQuery. Kolom ini kosong jika tabel BigQuery tidak memiliki kunci utama.
connectorInputPayload	JSON	Data sebenarnya yang akan ditambahkan atau diperbarui dalam entitas. Contoh berikut menunjukkan cuplikan JSON data baris yang akan ditambahkan dalam tabel: { "employee_first_name": "John", "employee_emailID": "[e-mail]" } Dalam contoh ini, employee_first_name dan employee_emailID adalah nama kolom dengan nilai terkait John dan [e-mail].
filterClause	String	Membatasi hasil operasi berdasarkan kondisi. Untuk informasi selengkapnya tentang cara menambahkan klausa filter, lihat Menambahkan filter untuk operasi.
listEntitiesPageSize	Bilangan bulat	Menentukan jumlah hasil yang harus ditampilkan di halaman. Halaman adalah pengelompokan data yang logis dalam set hasil. Konsep halaman berguna jika Anda mengharapkan sejumlah besar data dalam set hasil. Jika set hasil besar, tugas Konektor mungkin gagal, karena ada batasan ukuran data yang dapat diproses oleh tugas Konektor. Dengan membagi kumpulan hasil menjadi bagian yang lebih kecil, Anda dapat menghindari masalah ini. Misalnya, jika Anda mengharapkan 1.000 data dalam set hasil, Anda dapat menetapkan listEntitiesPageSize ke 100. Jadi, saat tugas Konektor dijalankan untuk pertama kalinya, tugas tersebut akan menampilkan 100 data pertama, 100 data berikutnya dalam operasi kedua, dan seterusnya. Penting: Ukuran halaman default adalah 25 dan jumlah maksimum halaman yang didukung oleh tugas adalah 50.000. Kecuali jika tabel atau set data Anda memiliki kunci utama, Anda harus menetapkan parameter listEntitiesSortByColumns untuk menggunakan listEntitiesPageToken. Gunakan parameter listEntitiesPageSize bersama dengan parameter listEntitiesPageToken untuk membuka halaman.
listEntitiesPageToken	String	ID halaman (token) yang memungkinkan Anda mengakses halaman tertentu. Anda bisa mendapatkan nilai token halaman dari parameter output listEntitiesNextPageToken. Karena setiap halaman memiliki token unik, Anda memiliki fleksibilitas untuk mengakses halaman apa pun yang Anda inginkan dalam set hasil. Untuk memahami penggunaan parameter ini, baca juga deskripsi parameter output listEntitiesNextPageToken.
listEntitiesSortByColumns	Array string	Nama kolom yang ingin Anda urutkan kumpulan hasilnya. Catatan: Anda dapat mengurutkan kumpulan hasil hanya berdasarkan satu kolom.

Parameter output

Tabel berikut menjelaskan parameter output untuk berbagai operasi entity.

Nama parameter	Jenis data	Deskripsi
connectorOutputPayload	JSON	Output operasi dalam format JSON.
listEntitiesNextPageToken	String	ID yang dibuat sistem untuk halaman. Anda dapat menganggap token sebagai pointer yang dapat digunakan untuk mengakses halaman tertentu dari kumpulan hasil. Jika telah membagi kumpulan hasil menjadi beberapa halaman dengan menetapkan parameter listEntitiesPageSize, Anda memerlukan mekanisme untuk menjelajahi halaman. Parameter output listEntitiesNextPageToken memungkinkan Anda melakukannya. Setiap kali tugas Konektor berjalan, sistem akan membuat token untuk halaman berikutnya dan menetapkan nilai listEntitiesNextPageToken ke token yang baru dibuat. Kemudian, Anda dapat menggunakan token ini untuk mengakses halaman berikutnya dalam set hasil. Untuk mengakses halaman berikutnya, Anda harus menetapkan parameter input listEntitiesPageToken ke nilai token halaman berikutnya. Misalnya, anggap Anda telah menetapkan parameter listEntitiesPageSize ke 2 dan saat tugas Konektor berjalan untuk pertama kalinya, listEntitiesNextPageToken ditetapkan ke nilai token ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Kemudian, Anda dapat menetapkan parameter input listEntitiesPageToken ke nilai token ini untuk mengambil halaman berikutnya dalam tugas Konektor berikutnya. Jika set hasil memiliki banyak halaman, Anda dapat mempertimbangkan untuk menggunakan tugas While Loop untuk mendapatkan halaman berikutnya dan menggunakan tugas Pemetaan Data untuk menetapkan nilai token halaman secara otomatis ke parameter input listEntitiesPageToken setelah setiap operasi dijalankan. Petakan listEntitiesNextPageToken dari iterasi loop terakhir ke listEntitiesPageToken di LIST Operation tugas Konektor iterasi loop saat ini. Tugas While Loop berakhir saat listEntitiesNextPageToken adalah NULL, yang menyiratkan bahwa tidak ada lagi halaman.

Klausa filter untuk operasi entity

Anda dapat membatasi data yang diproses oleh tugas Konektor menggunakan variabel Filter clause yang tersedia sebagai Task Input. Misalnya, dalam kasus operasi hapus, Anda dapat menambahkan klausa filter untuk menghapus data dengan orderId tertentu.

Klausa filter hanya dapat diterapkan untuk operasi entity berikut:

• Daftar
• Hapus
• Perbarui

Saat Anda memilih salah satu operasi ini, bagian Input Tugas dari tugas Konektor akan menampilkan kolom Filter clause secara otomatis.

Menambahkan klausa filter

Untuk menambahkan klausa filter, lakukan langkah-langkah berikut:

1. Klik elemen tugas Connectors di desainer untuk melihat panel konfigurasi tugas Connectors.
2. Luaskan bagian Task Input dan klik variabel string filterClause(Connectors).

   Dialog Configure Variable akan muncul.

3. Masukkan klausa filter (mengikuti sintaksis klausa) di kolom Nilai Default.
4. Klik Simpan.

Sintaksis dan contoh klausa filter

Klausa filter memiliki format berikut:

FIELD_NAME CONDITION FILTER_VALUE

Contoh

• OwnerId = '0053t000007941XAAQ'

• PoNumber < 2345

• OrderNumber = 00110 AND StatusCode = 'Draft'

• TotalAmount > 2500

• ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

Penting: Dalam klausa filter, tentukan nilai string dalam tanda kutip tunggal ( ' ) atau tanda kutip ganda ( " ) bergantung pada database yang Anda gunakan. Misalnya, MySQL menerima tanda kutip tunggal dan ganda, sedangkan BigQuery hanya menerima tanda kutip tunggal.

Penggunaan variabel dalam klausa filter

Anda tidak dapat langsung menggunakan variabel integrasi dalam klausa filter. Jika ingin menggunakan variabel integrasi, Anda harus mengonfigurasi tugas Pemetaan Data terlebih dahulu untuk membuat pemetaan antara variabel integrasi dan klausa filter.

Tabel berikut menunjukkan contoh pemetaan antara variabel integrasi dan variabel filterClause(Connectors):

Input	Output
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(')	filterClause(Connectors)

Dengan, PRIMARY_KEY_ID = ' dimasukkan sebagai Nilai di baris input.

---

Tindakan: Menjalankan kueri SQL kustom

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.

   

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.

      

   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=?

      Catatan: Pernyataan bahasa manipulasi data (DML) dan bahasa definisi data (DDL) didukung.
   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.

      

      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.

Pembaruan skema

Semua entitas dan tindakan akan memiliki skema yang terkait dengannya. Misalnya, skema tindakan akan memiliki detail parameter seperti; nama parameter, dan jenis data yang sesuai. Skema (metadata) untuk entity dan tindakan diambil oleh koneksi saat runtime dari backend Anda. Jika ada pembaruan pada skema, pembaruan tersebut tidak akan otomatis ditampilkan di koneksi yang ada; Anda harus memuat ulang skema secara manual. Untuk melihat skema yang diperbarui di tugas konektor yang ada, ikuti langkah-langkah berikut:

1. Di Integration Connectors, buka halaman Connection details koneksi, lalu klik Refresh connection schema.
2. Di Integrasi Aplikasi, Anda harus mengonfigurasi ulang tugas konektor yang ada untuk koneksi yang sama.

Pembuatan koneksi inline

Anda dapat menggunakan tugas Konektor untuk langsung membuat koneksi baru di Integration Connectors.

Sebelum memulai

• Menambahkan tugas Konektor

Membuat koneksi baru

Untuk membuat koneksi baru dari Integrasi Aplikasi, lakukan langkah-langkah berikut:

1. Klik elemen tugas Connectors di desainer untuk melihat panel konfigurasi tugas Connectors.
2. Klik Configure connector.

   Halaman Connectors Task Editor akan muncul.

3. Lewati kolom Region.
4. Klik Connection, lalu pilih opsi Create Connection dari menu drop-down.
5. Selesaikan langkah-langkah berikut di panel Create Connection:
   Catatan: Petunjuk berikut adalah langkah-langkah umum untuk membuat koneksi. Meskipun sebagian besar langkah tetap sama untuk semua jenis koneksi, beberapa langkah atau detail tambahan yang terkait dengan autentikasi dapat bervariasi.

   Sebaiknya Anda juga melihat dokumentasi jenis koneksi masing-masing di Konektor Integrasi.

   1. Pada langkah Location, pilih lokasi untuk koneksi.
      1. Klik Region, lalu pilih lokasi dari menu drop-down.
      2. Klik Berikutnya.
   2. Pada langkah Detail Koneksi, berikan detail tentang koneksi:
      1. Konektor: Pilih jenis konektor yang ingin Anda buat dari menu drop-down. Untuk mengetahui informasi tentang daftar konektor yang didukung, lihat Semua Konektor Integrasi.
      2. Versi konektor: Pilih versi yang tersedia dari jenis Konektor yang dipilih dari menu drop-down.
      3. Nama Koneksi: Masukkan nama untuk instance Koneksi.
         Catatan: 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 63 karakter.
      4. (Opsional) Masukkan Deskripsi untuk instance koneksi.
      5. (Opsional) Centang Enable Cloud Logging untuk menyimpan data log instance koneksi.
      6. Service Account: Pilih akun layanan yang memiliki peran yang diperlukan.
      7. (Opsional) Klik Setelan lanjutan untuk mengonfigurasi setelan node koneksi.

         Untuk mengetahui informasi selengkapnya, lihat dokumentasi koneksi masing-masing di Konektor Integrasi.

      8. (Opsional) Klik + TAMBAHKAN LABEL untuk menambahkan label ke koneksi dalam bentuk pasangan kunci/nilai.
      9. Klik Berikutnya.
   3. Pada langkah Autentikasi, berikan detail autentikasi untuk koneksi.
      1. Metode Autentikasi yang diisi selama langkah ini didasarkan pada jenis koneksi yang dibuat.

         Jenis koneksi yang berbeda menggunakan metode autentikasi yang berbeda. Untuk mengetahui informasi selengkapnya, lihat bagian Mengonfigurasi autentikasi dalam dokumentasi koneksi masing-masing di Konektor Integrasi.

      2. Klik Berikutnya.
   4. Tinjau: Tinjau detail koneksi dan autentikasi Anda.
   5. Klik Create.

---

Praktik terbaik

• Untuk mengetahui informasi tentang batas penggunaan yang berlaku untuk tugas Konektor, lihat Batas penggunaan.
• Untuk mengetahui informasi tentang cara memecahkan masalah tugas Konektor yang gagal, lihat Menggunakan log untuk memecahkan masalah dan melacak kegagalan konektor.

Strategi penanganan error

Strategi penanganan error untuk tugas menentukan tindakan yang akan diambil jika tugas gagal karena error sementara. Untuk mengetahui informasi tentang cara menggunakan strategi penanganan error, dan mengetahui berbagai jenis strategi penanganan error, lihat Strategi penanganan error.

Harga

Pemicu Cloud Pub/Sub dan pemicu Salesforce tidak mengharuskan Anda membuat konektor. Namun, jika Anda menggunakan Tugas konektor untuk terhubung ke Pub/Sub atau Salesforce, Anda akan ditagih untuk penggunaan konektor. Untuk mengetahui informasi tentang harga, lihat Harga Integrasi Aplikasi.

Kuota dan batas

Untuk mengetahui informasi tentang kuota dan batas, lihat Kuota dan batas.

Langkah selanjutnya

• Pelajari semua tugas dan pemicu.
• Pelajari cara menguji dan memublikasikan integrasi.
• Pelajari penanganan error.
• Pelajari log eksekusi integrasi.