Lihat konektor yang didukung untuk Application Integration.

Membuat konektor kustom

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Halaman ini menjelaskan cara membuat konektor kustom. Untuk memahami apa itu konektor kustom, lihat Konektor kustom.

Catatan: Konektor kustom adalah resource global; yang berarti setelah dibuat, Anda dapat menggunakannya di salah satu lokasi yang didukung untuk Integrasi Aplikasi.

Untuk membuat konektivitas ke backend menggunakan konektor kustom, Anda harus melakukan tugas berikut:

1. Buat konektor kustom - Dalam tugas ini, Anda akan menentukan kontrak antara Application Integration dan endpoint (backend) dengan memberikan spesifikasi OpenAPI endpoint. Saat ini, hanya OpenAPI versi 3.0 dan semua versi sekundernya yang didukung. Menentukan spesifikasi adalah aktivitas satu kali.
2. Membuat koneksi konektor kustom - Dalam tugas ini, Anda akan mengonfigurasi detail koneksi backend, seperti nama host dan autentikasi. Untuk konektor kustom tertentu, Anda dapat membuat koneksi sebanyak yang diperlukan.

Untuk memahami perbedaan antara konektor dan koneksi, lihat Konektor versus koneksi.

Sebelum memulai

• Untuk mendapatkan izin yang diperlukan guna membuat konektor kustom, minta administrator untuk memberi Anda peran IAM Custom Connectors Admin (roles/connectors.customConnectorAdmin) di project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

  Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

• Aktifkan Connector API:
  Aktifkan Connector API

Membuat konektor kustom

Seperti yang dijelaskan dalam skenario konektivitas backend, konektor kustom dapat memiliki salah satu pola konektivitas berikut:

• Konektivitas langsung ke endpoint publik backend Anda.
• Konektivitas tidak langsung ke backend Anda melalui endpoint publik perantara.

Langkah-langkah pembuatan konektor kustom sedikit berbeda untuk kedua pola ini.

Membuat dengan konektivitas langsung

Untuk membuat konektor kustom dengan konektivitas langsung ke endpoint backend Anda, lakukan langkah-langkah berikut:

Konsol

1. Di Konsol, buka halaman Application Integration > Custom connectors, lalu pilih atau buat project Google Cloud .

   Buka halaman Konektor kustom

2. Klik Buat baru untuk membuka halaman Buat konektor kustom.
3. Di bagian Connector details, tetapkan kolom berikut:
   1. Nama konektor: Masukkan nama untuk konektor.
   2. Nama tampilan: Masukkan nama tampilan untuk konektor.
   3. Deskripsi: Masukkan deskripsi.
   4. Akun layanan: Pilih akun layanan yang memiliki peran yang diperlukan.
   5. Logo: Upload gambar ke bucket Cloud Storage untuk menggunakannya sebagai logo konektor.
      Catatan: Pastikan pencegahan akses publik bucket Cloud Storage Anda dinonaktifkan.
4. Klik Berikutnya.
5. Di bagian Connector specification, tetapkan kolom berikut:
   1. Jenis konektor kustom: Pilih jenis konektor kustom.
   2. Spesifikasi konektor: Masukkan URL publik spesifikasi Open API Anda atau upload file spesifikasi Anda ke bucket Cloud Storage.
6. Tinjau detail konfigurasi konektor, lalu klik Buat.

Jika pembuatan konektor berhasil, konektor yang baru dibuat akan ditampilkan di Buka halaman Konektor kustom, dan jika konektor tersebut adalah konektor baru, versi pertama konektor juga akan dibuat. Anda dapat melihat detail versi di tab Versi di halaman Detail Konektor Kustom. Untuk mengetahui informasi selengkapnya, lihat .

Namun, perhatikan bahwa untuk terhubung ke backend, Anda harus membuat koneksi untuk konektor yang baru dibuat. Untuk mengetahui informasi selengkapnya, lihat Membuat koneksi konektor kustom.

API

Contoh perintah berikut menunjukkan cara membuat konektor kustom menggunakan API Integrasi Aplikasi:

1. Buat konektor.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -d '{"customConnectorType":"OPEN_API", \
   "displayName":"CUSTOM_CONNECTOR_NAME", \
   "description": "an open api based custom connector for hrms"}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
   

   Ganti kode berikut:

   • CUSTOM_CONNECTOR_NAME: Nama untuk konektor kustom.
   • PROJECT_ID: ID Google Cloud project Anda.
   • UNIQUE_IDENTIFIER: ID unik untuk konektor. Contohnya, custom-connector-1.
2. Konfigurasi versi konektor kustom.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{"spec_location": "SPECIFICATION_URL",}' \
   "https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"
   

Ganti kode berikut:

• SPECIFICATION_URL: URL spesifikasi Open API. Misalnya, https://petstore3.swagger.io/api/v3/openapi.json.
• PROJECT_ID: ID Google Cloud project Anda.
• VERSION_NUMBER: Nomor versi untuk konektor. Contoh, 2.

Membuat dengan konektivitas tidak langsung

Untuk membuat konektor kustom yang terhubung ke backend Anda melalui endpoint perantara, lakukan langkah-langkah berikut:

Konsol

1. Di Konsol, buka halaman Application Integration > Custom connectors, lalu pilih atau buat project Google Cloud .

   Buka halaman Konektor kustom

2. Klik Buat baru untuk membuka halaman Buat konektor kustom.
3. Di bagian Connector details, tetapkan kolom berikut:
   1. Nama konektor: Masukkan nama untuk konektor.
   2. Nama tampilan: Masukkan nama tampilan untuk konektor.
   3. Deskripsi: Masukkan deskripsi.
   4. Konfigurasi tujuan konektor untuk akses backend: Aktifkan opsi ini. Tindakan ini akan menampilkan bagian konfigurasi tambahan di halaman.
   5. Akun layanan: Pilih akun layanan yang memiliki peran yang diperlukan.
   6. Logo: Upload gambar ke bucket Cloud Storage untuk menggunakannya sebagai logo konektor.
      Catatan: Pastikan pencegahan akses publik bucket Cloud Storage Anda dinonaktifkan.
4. Klik Berikutnya.
5. Di bagian Connector specification, tetapkan kolom berikut:
   1. Jenis konektor kustom: Pilih jenis konektor kustom.
   2. Spesifikasi konektor: Masukkan URL publik spesifikasi Open API Anda atau upload file spesifikasi Anda ke bucket Cloud Storage.
6. Klik Berikutnya.
7. Di bagian Tujuan konektor, tetapkan kolom berikut:
   1. Jenis tujuan: Pilih Alamat host.
   2. Host: Masukkan nama host tempat layanan perantara Anda berjalan, dan sertakan skema http:// atau https://.
   3. Port: Masukkan nomor port layanan perantara Anda.
8. Klik Berikutnya.
9. Di bagian Autentikasi konektor, pilih jenis autentikasi layanan perantara, lalu masukkan detail yang sesuai seperti yang diminta. Langkah ini adalah untuk mengonfigurasi autentikasi dari Application Integration ke layanan perantara.

   Konfigurasi autentikasi dari layanan perantara ke backend tidak dapat dikonfigurasi di Application Integration; layanan perantara yang menentukan cara melakukan autentikasi dengan backend.

   Anda dapat menggunakan jenis autentikasi berikut untuk melakukan autentikasi ke layanan perantara:

   • Autentikasi Akun Layanan
   • Autentikasi Kunci API
   • OAuth 2.0 - Autentikasi Kredensial Klien
   • Autentikasi Dasar
   • Autentikasi Digest

   Untuk memahami cara mengonfigurasi jenis autentikasi ini, lihat Mengonfigurasi autentikasi.

   Jika akses ke resource API tidak dibatasi dan tidak memerlukan autentikasi apa pun, pilih Tanpa Autentikasi.

10. Klik Berikutnya.
11. Di bagian Variabel backend, masukkan nilai yang ingin Anda kirim ke backend melalui layanan perantara. Anda harus mengonfigurasi nilai sebagai pasangan nilai kunci. Untuk memasukkan pasangan nilai kunci, klik Tambahkan variabel, lalu tetapkan kolom berikut:
    • Key: Masukkan nama kunci.
    • Jenis nilai: Pilih jenis data variabel.
    • Nama tampilan: Masukkan nama tampilan.
    • Lokasi: Tentukan cara Anda ingin konektor mengirim variabel ke layanan perantara. Opsi yang tersedia adalah; Header, Request payload, dan Query parameter.
    • Opsional, pilih Required untuk menentukan bahwa variabel adalah variabel wajib.
    Catatan: Anda akan diminta untuk memasukkan nilai variabel yang dikonfigurasi saat membuat koneksi.
12. Klik Berikutnya.
13. Tinjau detail konfigurasi konektor, lalu klik Buat.

Jika pembuatan konektor berhasil, konektor yang baru dibuat akan ditampilkan di halaman Konektor kustom, dan jika konektor tersebut adalah konektor baru, versi pertama konektor juga akan dibuat. Anda dapat melihat detail versi di tab Versi di halaman Detail Konektor Kustom. Untuk mengetahui informasi tentang cara membuat dan mengedit versi konektor kustom, lihat Mengelola versi konektor kustom.

Namun, perhatikan bahwa untuk terhubung ke backend, Anda harus membuat koneksi untuk konektor yang baru dibuat. Untuk mengetahui informasi selengkapnya, lihat Membuat koneksi konektor kustom.

Mengonfigurasi autentikasi

Masukkan detail berdasarkan autentikasi yang ingin Anda gunakan.

• Autentikasi Akun Layanan

  Pilih opsi ini untuk melakukan autentikasi menggunakan akun layanan Google Cloud. Pastikan Anda telah memberikan peran dan izin IAM yang relevan kepada akun layanan yang diperlukan untuk autentikasi.

  • Cakupan: Pilih cakupan OAuth 2.0 yang diperlukan dari drop-down. Untuk mengetahui informasi selengkapnya, lihat Cakupan akses.
• Autentikasi kunci API

  Pilih opsi ini untuk melakukan autentikasi menggunakan kunci API.

  • Kunci API: Pilih secret Secret Manager dari kunci API.
  • Versi secret: Pilih versi secret.
  • Nama parameter kunci API: Masukkan nama parameter untuk kunci API. Kunci API dikirim ke server backend Anda sebagai pasangan nilai kunci. Nilai yang Anda masukkan di sini akan digunakan sebagai nama kunci untuk kunci API yang telah Anda pilih sebelumnya.
  • Lokasi kunci API: Pilih tempat Anda ingin menambahkan kunci API dalam permintaan.
• OAuth 2.0 - Pemberian kredensial klien
  • Client ID: ID klien yang akan digunakan untuk melakukan autentikasi ke layanan perantara.
  • Rahasia Klien: Secret Manager Secret yang berisi rahasia klien untuk melakukan autentikasi ke layanan perantara.
  • Format permintaan untuk token akses: Format permintaan yang akan digunakan dalam permintaan yang dibuat untuk mengambil token akses dari server autentikasi. Pilih body untuk meneruskan ID Klien dan Rahasia sebagai isi permintaan, atau header untuk meneruskannya sebagai header yang dienkode.
  • Jalur Permintaan Token: Jalur permintaan yang akan ditambahkan ke URL server autentikasi untuk mengambil URL token akses.
• Autentikasi Dasar
  • Nama pengguna: Nama pengguna yang digunakan untuk mengautentikasi ke layanan perantara.
  • Password: Secret Manager Secret yang berisi sandi yang terkait dengan nama pengguna yang diberikan.
• Autentikasi Digest
  • Nama pengguna: Nama pengguna yang digunakan untuk mengautentikasi ke layanan perantara.
  • Password: Secret Manager Secret yang berisi sandi yang terkait dengan nama pengguna yang diberikan.

API

Contoh perintah berikut menunjukkan cara membuat konektor kustom menggunakan API Integrasi Aplikasi:

1. Buat konektor.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -d '{"customConnectorType":"OPEN_API", \
   "displayName":"CUSTOM_CONNECTOR_NAME", \
   "description": "an open api based custom connector for hrms"}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
   

   Ganti kode berikut:

   • CUSTOM_CONNECTOR_NAME: Nama untuk konektor kustom.
   • PROJECT_ID: ID Google Cloud project Anda.
   • UNIQUE_IDENTIFIER: ID unik untuk konektor. Contohnya, custom-connector-1.
2. Konfigurasi versi konektor kustom dan autentikasi.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{"spec_location": "SPECIFICATION_URL", \
   "service_account":"test-sa", \
   "enable_backend_destination_config": true, \
   "auth_config": { \
   "auth_type":"USER_PASSWORD", \
   "auth_key": "basic", \
   "user_password": { \
   "username":"USERNAME", \
   "password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
   }}, \
   "backend_variable_templates": [{ \
   "key":"authkey", \
   "value_type":"SECRET", \
   "display_name":"Authorization Key", \
   "required":true, \
   "location_type": "HEADER" \
   }], \
   "destination_configs":[{ \
   "key":"base_url", \
   "destinations": [{ \
   "host":"DESTINATION_HOST_ADDRESS" \
   }]} \
   ]}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"
   

Ganti kode berikut:

• SPECIFICATION_URL: URL spesifikasi Open API. Misalnya, https://petstore3.swagger.io/api/v3/openapi.json.
• PROJECT_ID: ID Google Cloud project Anda.
• USERNAME: Nama pengguna untuk autentikasi dengan layanan perantara.
• SECRET_VERSION_NUMBER: Nomor versi secret Secret Manager. Contoh, 2.
• DESTINATION_HOST_ADDRESS: Alamat host layanan perantara. Contoh, http://www.test.com:80.
• CONNECTOR_VERSION_NUMBER: Nomor versi konektor kustom. Contoh, 1.
Catatan: Panggilan API contoh ini menggunakan autentikasi Username and Password. Berdasarkan persyaratan, Anda dapat menggunakan jenis autentikasi yang berbeda.

Membuat koneksi konektor kustom

Setelah membuat konektor kustom, untuk terhubung ke backend, Anda harus membuat koneksi jenis konektor kustom. Berikut adalah langkah-langkah tingkat tinggi untuk membuat koneksi baru:

1. Klik Buat baru untuk membuka halaman Buat koneksi.
2. Di bagian Location, pilih lokasi untuk koneksi dari kolom Region.

   Untuk mengetahui daftar semua region yang didukung, lihat Lokasi.

3. Klik Berikutnya.
4. Di bagian Connection details, tetapkan kolom berikut:
   1. Konektor: Pilih konektor kustom Anda dari menu drop-down daftar konektor yang tersedia.
   2. Versi konektor: Pilih versi Konektor dari daftar drop-down versi yang tersedia.
   3. Di kolom Nama koneksi, masukkan nama untuk koneksi.

      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. Secara opsional, masukkan Deskripsi untuk koneksi.
   5. Secara opsional, pilih Aktifkan Cloud Logging untuk mengaktifkan Cloud Logging.
   6. Akun layanan: Pilih akun layanan yang memiliki peran yang diperlukan.
   7. Jika perlu, konfigurasikan Setelan node koneksi:
      • Jumlah minimum node: Masukkan jumlah minimum node koneksi.
      • Jumlah node maksimum: Masukkan jumlah maksimum node koneksi.

      Node adalah unit (atau replika) koneksi yang memproses transaksi. Jumlah node yang diperlukan untuk memproses lebih banyak transaksi untuk suatu koneksi akan bertambah dan sebaliknya, jumlah node yang diperlukan untuk memproses lebih sedikit transaksi akan berkurang. 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.

   Catatan: Anda hanya dapat menyesuaikan nilai node koneksi jika Anda adalah pelanggan Bayar sesuai penggunaan.
   8. Secara opsional, klik Tambahkan label untuk menambahkan label ke koneksi dalam bentuk pasangan nilai kunci.
5. Klik Berikutnya.
6. Jika konektor menggunakan layanan perantara untuk terhubung ke backend Anda, lakukan hal berikut:

   Di bagian Tujuan, tetapkan kolom berikut:

   1. Jenis tujuan: Pilih Alamat host.
   2. Host: Masukkan nama host tempat layanan perantara Anda berjalan, dan sertakan skema http:// atau https://.
   3. Port: Masukkan nomor port layanan perantara Anda.

   Kolom tujuan berisi URL spesifikasi dari spesifikasi OpenAPI secara default. Jika ada beberapa URL server, URL pertama akan ditampilkan.

7. Klik Berikutnya.
8. Di bagian Authentication, masukkan detail autentikasi untuk backend Anda.
   • Jika Anda terhubung langsung ke backend, Integrasi Aplikasi akan meminta Anda untuk mengonfigurasi autentikasi untuk backend Anda.
   • Jika Anda terhubung secara tidak langsung ke backend melalui layanan perantara, Integrasi Aplikasi tidak akan meminta Anda untuk mengonfigurasi detail autentikasi. Saat membuat konektor, Anda sudah mengonfigurasi autentikasi antara Application Integration dan layanan perantara. Integrasi Aplikasi tidak mengharuskan Anda mengonfigurasi autentikasi antara layanan perantara dan backend; layanan perantara yang menentukan cara autentikasi dengan backend.
9. Klik Berikutnya.
10. Tinjau detail konfigurasi koneksi, lalu klik Buat.

Jika pembuatan koneksi berhasil, koneksi tersebut akan dicantumkan di halaman Semua koneksi, dan koneksi akan tersedia di Integrasi Aplikasi. Anda dapat menggunakan koneksi dalam integrasi melalui tugas Konektor.

Pertimbangan

Pertimbangkan poin-poin berikut saat membuat konektor kustom:

• Integrasi Aplikasi hanya mendukung OpenAPI versi 3.0 dan semua versi sekundernya.
• Spesifikasi Open API tidak divalidasi selama pembuatan konektor kustom. Saat Anda membuat koneksi untuk konektor kustom, Application Integration akan memvalidasi spesifikasi, dan jika ada error, koneksi akan berada dalam status Error.
• Integrasi Aplikasi tidak membedakan antara entitas dan tindakan. Oleh karena itu, entitas dan tindakan backend Anda akan dicantumkan sebagai Actions di konektor kustom Anda.
• Konektor kustom tidak didukung di Google Cloud project yang mengaktifkan Kontrol Layanan VPC.
• Endpoint spesifikasi Open API dan endpoint backend harus dapat diakses secara publik. Artinya, Anda tidak dapat membuat konektivitas pribadi ke backend.
• Jenis media multi-bagian tidak didukung dalam spesifikasi Open API.
• Anda tidak dapat mengedit detail versi konektor kustom.

Kuota dan batas

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

Langkah berikutnya

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