Tugas konektor

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

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

Guna 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 memiliki peran IAM Admin Connectors (roles/connectors.admin) di project Google Cloud. Untuk mengetahui informasi tentang cara memberikan peran, lihat Mengelola akses.
• Pelajari konsep umum Integration Connectors.
• Agar 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, akun layanan default (service-PROJECT_NUMBER@gcp-sa-apigee.) akan digunakan untuk autentikasi secara default.
• Pastikan akun layanan Anda memiliki peran IAM yang diperlukan. Untuk mengetahui 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 Anda.
2. Klik Develop > Integrasi.
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. Jika Anda ingin mengonfigurasi koneksi baru, klik dan tempatkan elemen Konektor di editor integrasi. Lalu, klik Konfigurasi konektor untuk mengonfigurasi koneksi.

   

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

   

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

   Atau, klik untuk mengganti nama nama tugas.

2. Klik Configure Connector.
3. Anda dapat memilih koneksi yang ada di region 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 Connectors Task Editor.

1. Di bagian Select connection, 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 Entitas, daftar entitas yang didukung untuk koneksi ditampilkan di bagian Tetapkan entitas/tindakan. Pilih diikuti oleh Operation yang ingin Anda lakukan pada entity tersebut.
   • Jika Anda memilih Tindakan, daftar tindakan yang didukung untuk koneksi akan ditampilkan di kolom Tetapkan entitas/tindakan. Pilih sebuah tindakan untuk koneksi.
   Entitas dan tindakan yang didukung didasarkan pada jenis konektor. Guna mengetahui daftar semua konektor yang didukung untuk Integrasi Apigee, lihat Referensi konektor. Untuk melihat tindakan dan entity yang didukung untuk sebuah konektor, lihat dokumentasi konektor tertentu.

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

   Catatan: Tidak semua jenis koneksi mendukung Entitas atau Tindakan. Jika jenis koneksi tidak mendukung tindakan atau entitas apa pun, Entitas dan Tindakan yang sesuai daftar ini 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 Connectors menampilkan Task Input dan variabel Output Tugas yang dibuat secara otomatis berdasarkan Entity dan Operasi atau Action dipilih di dialog Configure Connector task. Variabel-variabel ini dapat dikonfigurasi dan dapat diakses sebagai input untuk tugas saat ini atau sebagai output tugas berikutnya, atau kondisional dalam integrasi saat ini.

Untuk mengonfigurasi variabel Task Input atau Task Output, klik variabel masing-masing variabel untuk membuka panel Konfigurasi Variabel 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 informasi selengkapnya tentang input dan output parameter tugas Konektor, lihat Operasi entity.

Operasi dan tindakan entity

Anda dapat melakukan operasi CRUD (Membuat, Membaca, Memperbarui, Menghapus) pada entitas 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 dapat menggunakan operasi Get hanya untuk mengambil satu kumpulan data dari tabel yang memiliki {i>primary key<i}. 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 suatu {i>dataset.<i} Jika Anda menentukan nilai untuk entityId dan tabel atau tidak memiliki kolom {i>primary key<i}, integrasi 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 aktual yang akan ditambahkan atau diperbarui dalam suatu entitas. Contoh berikut menunjukkan Cuplikan JSON data baris yang akan ditambahkan ke dalam tabel: { "employee_first_name": "John", "employee_emailID": "[e-mail]" } Dalam contoh ini, employee_first_name dan employee_emailID adalah nama kolom dengan nilai yang sesuai John dan [e-mail].
filterClause	String	Membatasi hasil operasi berdasarkan suatu kondisi. Untuk informasi selengkapnya tentang 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 kumpulan hasil. Konsep halaman berguna saat Anda mengharapkan data dalam jumlah besar di set hasil. Jika kumpulan hasilnya besar, tugas Konektor mungkin gagal, karena batas ukuran data yang dapat diproses oleh tugas Konektor. Dengan menguraikan hasil menjadi potongan-potongan kecil, Anda dapat menghindari masalah ini. Misalnya, jika Anda mengharapkan 1.000 data dalam kumpulan hasil, Anda dapat listEntitiesPageSize menjadi 100. Jadi, saat tugas Konektor berjalan untuk pertama kali, ia mengembalikan 100 kumpulan data pertama, 100 kumpulan data berikutnya pada proses kedua, dan seterusnya. Penting: Ukuran halaman default adalah 25 dan jumlah maksimum halaman yang didukung tugas ini adalah 50.000. Anda harus menetapkan parameter listEntitiesSortByColumns untuk menggunakan listEntitiesPageToken, kecuali jika tabel atau set data Anda memiliki kunci utama. Gunakan hubungan parameter listEntitiesPageSize dengan parameter listEntitiesPageToken untuk membuka halaman.
listEntitiesPageToken	String	ID halaman (token) yang memungkinkan Anda mengakses halaman tertentu. Anda bisa mendapatkan nilai token halaman dari listEntitiesNextPageToken parameter output. Karena setiap laman memiliki token unik, Anda memiliki fleksibilitas untuk mengakses setiap laman inginkan dalam set hasil. Untuk memahami penggunaan parameter ini, baca juga deskripsi parameter output listEntitiesNextPageToken.
listEntitiesSortByColumns	Array string	Nama kolom yang ingin Anda gunakan untuk mengurutkan set hasil. Catatan: Anda dapat mengurutkan hasil yang ditetapkan hanya dengan 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 halaman. Anda dapat menganggap token sebagai penunjuk dengan yang memungkinkan Anda mengakses halaman tertentu dari set hasil. Jika Anda telah mengelompokkan hasil disetel menjadi beberapa halaman dengan menyetel parameter listEntitiesPageSize, membutuhkan suatu mekanisme untuk menavigasi halaman. listEntitiesNextPageToken parameter output memungkinkan Anda melakukan hal tersebut. Setiap kali tugas Konektor berjalan, sistem membuat token untuk halaman berikutnya dan menyetel atributlistEntitiesNextPageToken nilai ke token yang baru dibuat. Anda kemudian dapat menggunakan token ini untuk mengakses halaman berikutnya dalam set hasil. Untuk mengakses halaman berikutnya, Anda harus menyetel listEntitiesPageToken ke nilai token halaman berikutnya. Misalnya, Anda telah menetapkan parameter listEntitiesPageSize ke 2 dan ketika tugas Konektor berjalan untuk pertama kalinya, listEntitiesNextPageToken disetel ke Nilai token ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Anda kemudian dapat tetapkan parameter input listEntitiesPageToken ke nilai token ini untuk diambil halaman berikutnya dalam menjalankan tugas Konektor berikutnya. Jika kumpulan hasil Anda memiliki banyak halaman, Anda dapat mempertimbangkan untuk menggunakan Tugas Untuk Setiap Loop untuk berulang kali memanggil tugas Konektor dan menggunakan Pemetaan Data tugas untuk menetapkan nilai token secara otomatis ke Parameter input listEntitiesPageToken setiap kali dijalankan.

Klausa filter untuk operasi entity

Anda dapat membatasi record yang diproses oleh tugas Konektor menggunakan variabel Klausa filter yang tersedia sebagai Input Tugas. Misalnya, jika terjadi delete operasi, Anda dapat menambahkan klausa filter untuk menghapus kumpulan data dengan orderId khusus.

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 Klausa filter secara otomatis.

Menambahkan klausa filter

Untuk menambahkan klausa filter, lakukan langkah-langkah berikut:

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

   Dialog Konfigurasi Variabel akan muncul.

3. Masukkan klausa filter (dengan mengikuti klausa sintaksis) 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 ( " ) tergantung pada {i>database<i} yang 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 demikian, 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 mengonfigurasi tugas konektor, untuk jenis tindakan yang ingin Anda lakukan, pilih Tindakan.
3. Dalam daftar Action, pilih Execute custom query, lalu klik Done.

   

4. Luaskan bagian Task input, lalu lakukan hal berikut:
   1. Di kolom Timeout after, masukkan jumlah detik untuk menunggu hingga kueri dijalankan.

      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 Editor skrip akan terbuka.

      

   4. Dalam dialog Script editor, masukkan kueri SQL, lalu klik Save.

      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 Anda 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 menggantikan tanda tanya (?) dalam kueri SQL secara berurutan. Misalnya, jika Anda menambahkan tiga tanda tanya (?), Anda harus menambahkan tiga parameter secara berurutan.

      

      Untuk menambahkan parameter kueri, lakukan hal berikut:

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

Pembaruan skema

Semua entity dan tindakan akan memiliki skema yang terkait dengan entity tersebut. Misalnya, skema tindakan akan memiliki detail parameter seperti; parameter nama, dan tipe datanya yang sesuai. Skema (metadata) untuk entity dan tindakan diambil oleh koneksi di runtime dari backend Anda. Jika ada pembaruan pada skema, pembaruan tersebut tidak akan secara otomatis tercermin dalam koneksi Anda yang sudah ada; Anda harus memperbarui skema secara manual. Untuk melihat skema yang diperbarui di tugas konektor yang sudah ada, ikuti langkah-langkah berikut:

1. Di Integration Connectors, buka halaman Connection details dari koneksi, lalu klik Muat ulang skema koneksi.
2. Dalam Integrasi Apigee, 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

Buat koneksi baru

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

1. Klik elemen tugas Konektor pada desainer untuk melihat tugas Konektor panel konfigurasi.
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 terkait autentikasi dapat bervariasi.

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

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

         • Nama koneksi dapat menggunakan huruf, angka, atau tanda hubung.
         • Huruf harus huruf 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 Setelan lanjutan untuk mengonfigurasi setelan node koneksi.

         Untuk 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 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 masing-masing di Konektor Integrasi.

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

---

Praktik terbaik

• Untuk mengetahui informasi tentang batas penggunaan yang berlaku bagi 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 informasi tentang cara menggunakan strategi penanganan error, dan mengetahui berbagai jenis strategi penanganan error, lihat Strategi penanganan error.