Membuat konektor kustom

Halaman ini menjelaskan cara membuat konektor kustom. Untuk memahami apa yang dimaksud dengan konektor kustom, lihat Konektor kustom.

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

  1. Membuat konektor kustom - Dalam tugas ini, Anda akan menentukan kontrak antara Konektor Integrasi dan endpoint (backend) dengan memberikan spesifikasi OpenAPI endpoint. Saat ini, hanya OpenAPI versi 3.0 dan semua versi minornya 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

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, lakukan langkah-langkah berikut:

Konsol

  1. Di Konsol, buka halaman Konektor Integrasi > Konektor kustom, lalu pilih atau buat project Google Cloud .

    Buka halaman Konektor kustom

  2. Klik Buat baru untuk membuka halaman Buat konektor kustom.
  3. Di bagian Detail konektor, 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.
  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 ke bucket Cloud Storage.
  6. Tinjau detail konfigurasi konektor, lalu klik Create.

Jika pembuatan konektor berhasil, konektor yang baru dibuat akan ditampilkan di Buka halaman Konektor kustom, dan jika ini adalah konektor baru, versi pertama konektor juga akan dibuat. Anda dapat melihat detail versi di tab Version di halaman Custom Connector details. Untuk informasi selengkapnya, lihat .

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

API

Contoh perintah berikut menunjukkan cara membuat konektor kustom menggunakan Integration Connectors API:

  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 project Google Cloud Anda.
    • UNIQUE_IDENTIFIER: ID unik untuk konektor. Contohnya, custom-connector-1.
  2. Konfigurasikan 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"

    3. Ganti kode berikut:

    • SPECIFICATION_URL: URL spesifikasi Open API. Misalnya, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: ID project Google Cloud 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 Konektor Integrasi > Konektor kustom, lalu pilih atau buat project Google Cloud .

    Buka halaman Konektor kustom

  2. Klik Buat baru untuk membuka halaman Buat konektor kustom.
  3. Di bagian Detail konektor, tetapkan kolom berikut:
    1. Nama konektor: Masukkan nama untuk konektor.
    2. Nama tampilan: Masukkan nama tampilan untuk konektor.
    3. Deskripsi: Masukkan deskripsi.
    4. Konfigurasikan 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.
  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 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.
    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 Konektor Integrasi ke layanan perantara.

    Konfigurasi autentikasi dari layanan perantara ke backend tidak dapat dikonfigurasi di Konektor Integrasi; layanan perantara dapat memilih cara melakukan autentikasi dengan backend.

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

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

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

    Jika akses ke resource API tidak dibatasi dan tidak memerlukan autentikasi apa pun, pilih Tidak Ada 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 key-value pair. Untuk memasukkan pasangan nilai kunci, klik Tambahkan variabel, lalu tetapkan kolom berikut:
    • Kunci: Masukkan nama kunci.
    • Jenis nilai: Pilih jenis data variabel.
    • Nama tampilan: Masukkan nama tampilan.
    • Location: Tentukan cara Anda ingin konektor mengirim variabel ke layanan perantara. Opsi yang tersedia adalah; Header, Request payload, dan Query parameter.
    • Secara opsional, pilih Required untuk menentukan bahwa variabel tersebut adalah variabel wajib.
  12. Klik Berikutnya.
  13. Tinjau detail konfigurasi konektor, lalu klik Create.

Jika pembuatan konektor berhasil, konektor yang baru dibuat akan ditampilkan di halaman konektor kustom, dan jika ini adalah konektor baru, versi pertama konektor juga akan dibuat. Anda dapat melihat detail versi di tab Version di halaman Custom Connector details. Untuk mengetahui informasi tentang cara membuat dan mengedit versi konektor kustom, lihat Mengelola versi konektor kustom.

Namun, perlu diperhatikan bahwa untuk terhubung ke backend, Anda harus membuat koneksi untuk konektor yang baru dibuat. Untuk 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 yang diperlukan untuk autentikasi kepada akun layanan.

    • Cakupan: Pilih cakupan OAuth 2.0 yang diperlukan dari drop-down. Untuk 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.
    • API key parameter name: 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: Client ID yang akan digunakan untuk mengautentikasi ke layanan perantara.
    • Rahasia Klien: Rahasia Secret Manager yang berisi rahasia klien untuk mengautentikasi 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 client ID dan Secret sebagai isi permintaan, atau header untuk meneruskannya sebagai header yang dienkode.
    • Token Request Path: 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.
    • Sandi: Secret Manager Secret yang berisi sandi yang terkait dengan nama pengguna yang diberikan.
  • Digest Authentication
    • Nama pengguna: Nama pengguna yang digunakan untuk mengautentikasi ke layanan perantara.
    • Sandi: Secret Manager Secret yang berisi sandi yang terkait dengan nama pengguna yang diberikan.

API

Contoh perintah berikut menunjukkan cara membuat konektor kustom menggunakan Integration Connectors API:

  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 project Google Cloud Anda.
    • UNIQUE_IDENTIFIER: ID unik untuk konektor. Contohnya, custom-connector-1.
  2. Konfigurasikan 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"

    3. Ganti kode berikut:

    • SPECIFICATION_URL: URL spesifikasi Open API. Misalnya, https://petstore3.swagger.io/api/v3/openapi.json.
    • PROJECT_ID: ID project Google Cloud 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.

Membuat koneksi konektor kustom

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

  1. Di konsol Cloud, buka halaman Konektor Integrasi > Koneksi, lalu pilih atau buat project Google Cloud.

    Buka halaman Koneksi

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

    Untuk mengetahui daftar semua region yang didukung, lihat Lokasi.

  4. Klik Berikutnya.
  5. Di bagian Connection details, tetapkan kolom berikut:
    1. Konektor: Pilih konektor kustom Anda dari menu drop-down konektor yang tersedia.
    2. Versi konektor: Pilih versi Konektor dari menu 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 Description untuk koneksi.
    5. Secara opsional, pilih Aktifkan logging cloud untuk mengaktifkan logging cloud.
    6. Service account: Pilih akun layanan yang memiliki peran yang diperlukan.
    7. Secara opsional, konfigurasikan Setelan node koneksi:

      • Jumlah node minimum: Masukkan jumlah minimum node koneksi.
      • Maximum number of nodes: Masukkan jumlah maksimum node koneksi.

      Node adalah unit (atau replika) koneksi yang memproses transaksi. Semakin banyak node yang diperlukan untuk memproses lebih banyak transaksi untuk koneksi, dan sebaliknya, semakin sedikit node yang diperlukan untuk memproses lebih sedikit transaksi. Untuk memahami pengaruh node terhadap harga konektor Anda, 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.

    8. Secara opsional, klik Tambahkan label untuk menambahkan label ke koneksi dalam bentuk pasangan nilai kunci.
  6. Klik Berikutnya.
  7. Di bagian Authentication, masukkan detail autentikasi untuk backend Anda.
    • Jika Anda terhubung langsung ke backend, Konektor Integrasi akan meminta Anda untuk mengonfigurasi autentikasi untuk backend Anda.
    • Jika Anda terhubung secara tidak langsung ke backend melalui layanan perantara, Integration Connectors tidak akan meminta Anda untuk mengonfigurasi detail autentikasi. Saat membuat konektor, Anda akan mengonfigurasi autentikasi antara Konektor Integrasi dan layanan perantara. Konektor Integrasi tidak mengharuskan Anda mengonfigurasi autentikasi antara layanan perantara dan backend; layanan perantara dapat menentukan cara mengautentikasi dengan backend.
  8. Klik Berikutnya.
  9. Tinjau detail konfigurasi koneksi, lalu klik Create.

Jika pembuatan koneksi berhasil, koneksi tersebut akan tercantum 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:

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