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 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.

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 ([e-mail]) 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 > 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.

   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:
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 Entitas, daftar entitas yang didukung untuk koneksi ditampilkan di bagian Tetapkan entitas/tindakan. Pilih entity, diikuti dengan 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 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, 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.

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 dibuat 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 tugas berikutnya, atau kondisional dalam integrasi saat ini.

Untuk mengonfigurasi variabel Task Input atau Task Output, klik variabel terkait untuk membuka panel Konfigurasikan Variabel, lalu 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 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 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 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 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 jika Anda mengharapkan sejumlah besar data dalam kumpulan hasil. Jika kumpulan hasilnya besar, tugas Konektor mungkin gagal, karena ada batas ukuran data yang dapat diproses oleh tugas Konektor. Dengan memecah hasil menjadi beberapa bagian yang lebih kecil, Anda dapat menghindari masalah ini. Misalnya, jika Anda mengharapkan 1.000 data dalam kumpulan hasil, Anda dapat menetapkan listEntitiesPageSize ke 100. Jadi, saat tugas Konektor berjalan untuk pertama kalinya, tugas akan menampilkan 100 kumpulan data pertama, 100 kumpulan data berikutnya dalam 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 parameter output listEntitiesNextPageToken. Karena setiap halaman memiliki token unik, Anda memiliki fleksibilitas untuk mengakses halaman apa pun yang diinginkan dalam kumpulan 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 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 dihasilkan sistem untuk halaman. Anda dapat menganggap token sebagai pointer yang dapat digunakan untuk mengakses halaman tertentu dari kumpulan hasil. Jika telah mengelompokkan hasil menjadi beberapa halaman dengan menetapkan parameter listEntitiesPageSize, Anda memerlukan mekanisme untuk menjelajahi halaman-halaman tersebut. Parameter output listEntitiesNextPageToken memungkinkan Anda melakukan hal tersebut. Setiap kali tugas Konektor berjalan, sistem akan membuat token untuk halaman berikutnya dan menetapkan nilai listEntitiesNextPageToken ke token yang baru dibuat. Anda kemudian 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, Anda telah menetapkan parameter listEntitiesPageSize ke 2 dan saat tugas Konektor berjalan untuk pertama kalinya, listEntitiesNextPageToken ditetapkan ke nilai token ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Selanjutnya, Anda dapat menetapkan parameter input listEntitiesPageToken ke nilai token ini untuk mengambil halaman berikutnya pada proses berikutnya untuk tugas Konektor. Jika kumpulan hasil memiliki banyak halaman, Anda dapat mempertimbangkan untuk menggunakan tugas For Setiap Loop agar dapat berulang kali memanggil tugas Konektor dan menggunakan tugas Pemetaan Data untuk secara otomatis menetapkan nilai token ke parameter input listEntitiesPageToken setelah 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, dalam kasus 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
• Perbarui

Saat Anda memilih salah satu operasi ini, bagian Input Tugas dari tugas Konektor menampilkan kolom Klausa filter 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 Konfigurasi Variabel akan muncul.

3. Masukkan klausa filter (dengan mengikuti klausa syntax) 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 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 Input tugas, lalu lakukan tindakan 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 nama parameter, dan jenis datanya 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 diterapkan pada koneksi yang ada; Anda harus memperbarui skema secara manual. Untuk melihat skema yang diperbarui pada tugas konektor yang sudah ada, ikuti langkah-langkah berikut:

1. Di Integration Connectors, buka halaman Connection details dari koneksi, lalu klik Refresh connection schema.
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 Connectors pada 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 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.