Tugas konektor

Pengumuman: Application Integration kini tersedia untuk project Google Cloud Anda. Anda kini dapat menggunakan Integrasi Apigee dan Application Integration dalam project Google Cloud yang sama. Pelajari lebih lanjut

Dengan tugas Connectors, Anda dapat terhubung dengan cepat dan aman ke berbagai layanan Google Cloud dan aplikasi bisnis lainnya dari integrasi Anda menggunakan konektor siap pakai yang tersedia di Integration Connectors.

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

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

Sebelum memulai

• Pastikan Anda telah diberi peran IAM Connectors Admin (roles/connectors.admin) 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 belum mengonfigurasi akun layanan yang dikelola pengguna, akun layanan default ([e-mail]) akan digunakan untuk autentikasi secara default.
• 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 UI Apigee, pilih Organisasi Apigee.
2. Klik Develop > Integrations.
3. Pilih integrasi yang ada atau buat integrasi baru dengan mengklik Buat Integrasi.

   Jika Anda membuat integrasi baru:

   1. Masukkan nama dan deskripsi dalam dialog Create Integration.
   2. Pilih Region untuk integrasi dari daftar wilayah yang didukung.
   3. Klik Create.

   Tindakan ini akan membuka integrasi di desainer integrasi.

4. Di menu navigasi desainer integrasi, klik +Tambahkan tugas/pemicu > Tasks untuk melihat daftar tugas yang tersedia.
5. Klik dan tempatkan elemen Connectors di editor integrasi.

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 pada desainer untuk melihat panel konfigurasi tugas Connectors.

   Anda juga dapat mengklik untuk mengganti nama nama tugas.

2. Klik Konfigurasi konektor.
3. Anda dapat memilih koneksi yang ada di region tersebut atau membuat koneksi baru. Untuk mengonfigurasi koneksi yang ada, selesaikan langkah-langkah berikut di halaman Connectors Task Editor:
1. Untuk Select Connectors, pilih region koneksi.
2. Pilih koneksi yang ada dari daftar koneksi yang tersedia di region yang dipilih.
3. Klik Next.
4. Dari daftar Jenis, pilih Entitas atau Tindakan.
   • Jika Anda memilih Entity, daftar entity yang didukung untuk koneksi akan ditampilkan di bagian Menetapkan entity/actions. Pilih entitas diikuti dengan Operasi yang ingin Anda lakukan pada entitas tersebut.
   • Jika Anda memilih Tindakan, daftar tindakan yang didukung untuk koneksi akan ditampilkan di kolom Tetapkan entity/actions. Pilih tindakan untuk koneksi.
   Entitas dan tindakan yang didukung didasarkan pada jenis konektor. Untuk mengetahui daftar semua konektor yang didukung untuk Integrasi Apigee, lihat Referensi konektor. Untuk melihat tindakan dan entity yang didukung untuk konektor, lihat dokumentasi konektor tertentu.

   Jika konektor mendukung kueri SQL kustom, Anda dapat memilih opsi Jalankan kueri kustom dari daftar Tindakan. Misalnya, untuk melihat cara menambahkan kueri SQL kustom untuk konektor BigQuery, lihat Menjalankan kueri SQL kustom.

   Untuk mengetahui informasi selengkapnya tentang entitas dan tindakan, lihat Entitas, operasi, dan tindakan.

   Catatan: Tidak semua jenis koneksi mendukung Entity atau Actions. Jika jenis koneksi tidak mendukung tindakan atau entitas apa pun, daftar Entity dan Actions yang sesuai akan kosong.
5. Klik Done untuk menyelesaikan konfigurasi koneksi dan menutup panel.

Gambar berikut menunjukkan contoh tata letak halaman Connectors Task Editor.

Mengonfigurasi variabel input dan output tugas

Panel konfigurasi tugas Connectors menampilkan variabel Task Input dan Task Output yang otomatis dihasilkan berdasarkan Entity and Operation atau Action yang dipilih dalam 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 Nilai Default.
2. (Opsional) Pilih Gunakan sebagai input untuk integrasi atau Gunakan sebagai output untuk integrasi.
3. Klik Simpan.

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

Operasi entitas

Anda dapat melakukan operasi CRUD (Membuat, Membaca, Memperbarui, Menghapus) 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 data dari tabel yang memiliki kunci utama. Atau, Anda dapat menggunakan operasi List dengan filterClause.
Buat	connectorInputPayload	connectorOutputPayload
Pembaruan	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 dari 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 Connectors 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 aktual yang akan ditambahkan atau diperbarui dalam suatu entitas. Contoh berikut menunjukkan cuplikan JSON dari 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 John dan [e-mail] yang sesuai.
filterClause	String	Membatasi hasil operasi berdasarkan suatu kondisi. Untuk mengetahui informasi selengkapnya mengenai penambahan klausa filter, baca artikel Menambahkan filter untuk operasi.
listEntitiesPageSize	Bilangan bulat	Menentukan jumlah hasil yang harus ditampilkan di halaman. Halaman adalah pengelompokan kumpulan data secara logis dalam suatu kumpulan hasil. Konsep halaman berguna ketika Anda mengharapkan banyak data dalam kumpulan hasil. Jika kumpulan hasilnya besar, tugas Connector mungkin akan gagal, karena ada batas ukuran data yang dapat diproses oleh tugas Connectors. Dengan membagi hasil menjadi potongan-potongan kecil, Anda dapat menghindari masalah ini. Misalnya, jika Anda mengharapkan 1.000 data dalam kumpulan hasil, Anda dapat menetapkan listEntitiesPageSize ke 100. Jadi, saat berjalan untuk pertama kalinya, tugas Connectors akan menampilkan 100 data pertama, 100 data berikutnya pada proses kedua, dan seterusnya. Penting: Ukuran halaman default adalah 25 dan jumlah maksimum halaman yang didukung oleh tugas ini adalah 200. Kecuali jika tabel atau set data memiliki kunci utama, Anda harus menetapkan parameter listEntitiesSortByColumns untuk menggunakan listEntitiesPageToken. Gunakan gabungan parameter listEntitiesPageSize dengan parameter listEntitiesPageToken untuk menjelajahi 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 kumpulan hasil. Untuk memahami penggunaan parameter ini, baca juga deskripsi parameter output listEntitiesNextPageToken.
listEntitiesSortByColumns	Array string	Nama kolom yang Anda inginkan untuk mengurutkan hasil yang ditetapkan. Catatan: Anda hanya dapat mengurutkan hasil yang ditetapkan menurut 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 dihasilkan sistem untuk sebuah halaman. Anda dapat menganggap token ini sebagai pointer yang dapat Anda gunakan untuk mengakses halaman tertentu dari kumpulan hasil. Jika telah membagi hasil Anda menjadi beberapa halaman dengan menetapkan parameter listEntitiesPageSize, Anda memerlukan mekanisme untuk menjelajahi halaman tersebut. Parameter output listEntitiesNextPageToken memungkinkan Anda melakukan hal tersebut. Setiap kali tugas Konektor berjalan, sistem akan menghasilkan token untuk halaman berikutnya dan menetapkan nilai listEntitiesNextPageToken ke token yang baru dihasilkan. Selanjutnya Anda dapat menggunakan token ini untuk mengakses halaman berikutnya di kumpulan hasil. Untuk mengakses halaman berikutnya, Anda harus menetapkan parameter input listEntitiesPageToken ke nilai token halaman berikutnya. Misalnya, anggap Anda telah menyetel parameter listEntitiesPageSize ke 2, dan saat tugas Konektor berjalan untuk pertama kalinya, listEntitiesNextPageToken disetel ke nilai token ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Selanjutnya, Anda dapat menetapkan parameter input listEntitiesPageToken ke nilai token ini untuk mengambil halaman berikutnya pada proses selanjutnya dari tugas Connectors. Jika kumpulan hasil Anda memiliki halaman dalam jumlah besar, Anda dapat mempertimbangkan penggunaan tugas For Setiap Loop untuk memanggil tugas Konektor berulang kali dan menggunakan tugas Pemetaan Data guna menetapkan nilai token secara otomatis ke parameter input listEntitiesPageToken setelah setiap sesi dijalankan.

Klausa filter untuk operasi entity

Anda dapat membatasi data yang diproses oleh tugas Connectors menggunakan variabel Klausa Filter yang tersedia sebagai Input Tugas. Misalnya, dalam operasi delete, Anda dapat menambahkan klausa filter untuk menghapus kumpulan data dengan orderId tertentu.

Klausa filter hanya dapat diterapkan untuk operasi entity berikut:

• Daftar
• Hapus
• Pembaruan

Jika Anda memilih salah satu operasi ini, bagian Task Input pada tugas Connectors akan menampilkan kolom Filter klausa secara otomatis.

Menambahkan klausa filter

Untuk menambahkan klausa filter, lakukan langkah-langkah berikut:

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

   Dialog Configure Variable akan muncul.

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

Sintaksis klausa filter dan contohnya

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 terlebih dahulu mengonfigurasi tugas Pemetaan Data 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.

---

Pembuatan koneksi inline

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

Sebelum memulai

• Menambahkan tugas Konektor

Buat koneksi baru

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

1. Klik elemen tugas Connectors pada desainer untuk melihat panel konfigurasi tugas Connectors.
2. Klik Konfigurasi konektor.

   Halaman Connectors Task Editor akan muncul.

3. Lewati kolom Region.
4. Klik Connection, lalu pilih opsi Create Connection di 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 langkahnya tetap sama untuk semua jenis koneksi, beberapa langkah atau detail tambahan yang terkait dengan autentikasi mungkin bervariasi.

   Sebaiknya Anda juga melihat dokumentasi jenis koneksi masing-masing dalam Integrasi Integrasi.

   1. Pada langkah Lokasi, pilih lokasi untuk koneksi.
      1. Klik Region dan pilih lokasi dari menu drop-down.
      2. Klik Next.
   2. Pada langkah Connection Details, 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 untuk jenis Konektor yang dipilih dari menu drop-down.
      3. Connection Name: Masukkan nama untuk instance Connection.
         Catatan: Nama koneksi harus memenuhi kriteria berikut:

         • Nama koneksi dapat menggunakan huruf, angka, atau tanda hubung.
         • Huruf harus kecil.
         • Nama koneksi harus dimulai dengan huruf dan diakhiri dengan huruf atau angka.
         • Nama koneksi tidak boleh lebih dari 63 karakter.
      4. (Opsional) Masukkan Deskripsi untuk instance koneksi.
      5. (Opsional) Centang Enable Cloud Logging untuk menyimpan data log instance koneksi.
      6. Akun Layanan: Pilih akun layanan yang memiliki peran yang diperlukan.
      7. (Opsional) Klik Advanced settings untuk mengonfigurasi setelan node koneksi.

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

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

         Jenis koneksi yang berbeda menggunakan metode autentikasi yang berbeda. Untuk informasi selengkapnya, lihat bagian Mengonfigurasi autentikasi dalam dokumentasi koneksi terkait dalam Konektor Integrasi.

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

---

Praktik terbaik

• Guna 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 mendapatkan informasi tentang cara menggunakan strategi penanganan error, dan mengetahui berbagai jenis strategi penanganan error, lihat Strategi penanganan error.