Menambahkan API sebagai penyedia jenis

Halaman ini menjelaskan cara menambahkan API ke Google Cloud Deployment Manager sebagai penyedia jenis. Untuk mempelajari penyedia jenis dan jenis lebih lanjut, baca dokumentasi Ringkasan jenis.

Penyedia jenis mengekspos semua resource API pihak ketiga ke Deployment Manager sebagai jenis dasar yang dapat Anda gunakan dalam konfigurasi. Jenis ini harus disalurkan langsung oleh RESTful API yang mendukung Buat, Baca, Update, dan Hapus (CRUD).

Jika ingin menggunakan API yang tidak otomatis disediakan oleh Google dengan Deployment Manager, Anda harus menambahkan API sebagai penyedia jenis. Anda dapat menambahkan API apa pun sebagai penyedia jenis selama API tersebut memiliki spesifikasi OpenAPI (sebelumnya Swagger^©), atau dokumen Google Discovery.

Dokumen ini tidak menjelaskan cara membuat layanan API Anda sendiri. Asumsinya adalah sudah ada API yang ingin Anda tambahkan, atau Anda sudah membuat API berjalan yang dapat diakses dari endpoint publik. Misalnya, untuk men-deploy contoh API menggunakan Endpoint Google Cloud, Anda dapat mengikuti Panduan Memulai Cloud Endpoints.

Sebelum memulai

Jika Anda ingin menggunakan contoh command line dalam panduan ini, instal alat command line`gcloud`.
Jika Anda ingin menggunakan contoh API dalam panduan ini, siapkan akses API.
Siapkan akses API v2beta jika Anda ingin menggunakan contoh API dalam panduan ini.

Komponen penyedia jenis

Penyedia jenis terdiri dari:

Nama: Nama penyedia jenis yang diinginkan. Anda akan menggunakan nama ini untuk mereferensikan jenis dan resource API yang relevan.
Dokumen deskriptor: URL dokumen deskripsi untuk jenis. Dokumen yang didukung mencakup dokumen Google Discovery atau spesifikasi OpenAPI 1.2.
Autentikasi: Kredensial autentikasi apa pun yang diperlukan untuk API. Anda dapat menentukan autentikasi dasar. Jika API Anda berjalan di Cloud Endpoints atau Google Kubernetes Engine (GKE), Anda juga dapat menggunakan kredensial akun layanan project sebagai autentikasi.
Opsi lanjutan: Pemetaan input atau opsi API lanjutan apa pun.

Nama

Nama penyedia jenis. Anda akan menggunakan nama ini untuk merujuk ke jenis tersebut dalam konfigurasi dan template mendatang. Misalnya, jika Anda membuat penyedia jenis dan menamainya my-awesome-type-provider, Anda akan menggunakannya di template berikutnya seperti berikut:

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

dengan my-project adalah project ID yang memiliki jenis dan some-collection adalah jalur ke resource API yang Anda buat.

Dokumen deskriptor

Dokumen deskripsi untuk penyedia jenis dapat berupa spesifikasi OpenAPI 1.2 atau 2.0, atau dokumen Google Discovery. Misalnya, Anda dapat menemukan dokumen Google Discovery untuk Compute Engine Beta API di URL ini:

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

Lihat daftar lengkap dokumen Google Discovery.

Dokumen OpenAPI 1.2 dan OpenAPI 2.0 juga dapat diterima.

Authentication

Jika API Anda memerlukan autentikasi, Anda dapat memberikan detail autentikasi di sini. Deployment Manager mendukung kredensial autentikasi dasar, seperti nama pengguna dan sandi. Untuk Google Kubernetes Engine dan Endpoint Google Cloud, Anda dapat menggunakan header Authorization untuk menyediakan token akses dari akun layanan project.

Untuk menentukan kredensial autentikasi dasar, berikan nama pengguna dan sandi di bagian credentials:

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Anda hanya perlu menentukan nama pengguna dan sandi saat pertama kali membuat penyedia jenis.

Jika memiliki cluster yang berjalan di Google Kubernetes Engine (GKE) di project yang sama tempat Anda menggunakan Deployment Manager, Anda dapat menambahkan cluster sebagai penyedia jenis dan menggunakan Deployment Manager untuk mengakses GKE API. Dalam skenario ini, Anda bisa mendapatkan token akses OAuth 2.0 dari akun layanan Google API project dan memberikan token akses tersebut di header Authorization. Tidak seperti di bagian kredensial sebelumnya, Anda harus menyediakannya sebagai pemetaan input dalam permintaan Anda:

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

Metode googleOauth2AccessToken() akan otomatis mendapatkan token akses saat pengguna memanggil penyedia jenis ini. Untuk contoh lengkapnya, lihat contoh Cluster dan Jenis GKE.

Anda dapat menggunakan metode yang sama untuk melakukan autentikasi ke Endpoint Google Cloud.

(Opsional) Root Certificate Authority Kustom

Jika ingin menambahkan API sebagai penyedia jenis ke Deployment Manager, dan endpoint HTTPS API tersebut menggunakan sertifikat yang tidak disediakan oleh Certificate Authority (CA) yang tepercaya secara publik untuk mengenkripsi koneksi, Anda dapat menambahkan API tersebut ke konfigurasi seperti pada contoh berikut:

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

dengan my-gke-cluster adalah cluster GKE yang Anda gunakan. Untuk mengetahui contoh mendetail, lihat contoh Cluster Penyedia GKE.

Opsi jenis lanjutan

API tertentu mungkin memiliki keunikan yang menyulitkan Deployment Manager untuk memetakan semua properti API ke Deployment Manager. Dalam skenario ideal, Anda menyediakan dokumen deskriptor dan Deployment Manager akan otomatis mencari tahu jalur permintaan API dan properti API yang relevan tanpa perlu melakukan tindakan tambahan apa pun. Untuk API yang lebih kompleks, Deployment Manager dapat memahami sebagian besar API, tetapi Anda mungkin perlu secara eksplisit menentukan pemetaan input ke perilaku API yang tidak jelas.

Untuk mempelajari pemetaan input lebih lanjut, baca dokumentasi untuk Opsi API Lanjutan.

Membuat penyedia jenis

Untuk membuat penyedia jenis, buat permintaan ke Deployment Manager dengan payload permintaan yang berisi nama penyedia jenis yang diinginkan, URL deskriptor, dan kredensial autentikasi yang diperlukan.

gcloud

Untuk membuat penyedia jenis menggunakan gcloud CLI, gunakan perintah type-providers create:

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

dengan:

[TYPE_PROVIDER_NAME] adalah nama yang ingin Anda berikan untuk jenis ini.
[URL] adalah URL yang sepenuhnya memenuhi syarat untuk dokumen deskripsi yang mendukung jenis ini. Contoh:
```
http://petstore.swagger.io/v2/swagger.json
```

Jika ingin memberikan kredensial autentikasi atau opsi API lanjutan, Anda dapat membuat file opsi API yang ditulis dalam YAML dan memberinya menggunakan flag --api-options-file. Misalnya, file mungkin terlihat seperti ini:

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Perintah gcloud adalah:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

Jika ingin melakukan autentikasi menggunakan Certificate Authority (CA) kustom, Anda dapat menambahkan CA sebagai flag ke perintah gcloud, seperti dalam contoh berikut:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

API

Untuk membuat jenis dasar di API, buat permintaan POST yang berisi descriptorUrl dan opsi konfigurasi opsional dalam isi permintaan. Contoh:

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

Untuk informasi selengkapnya, lihat dokumentasi untuk metode insert.

Menguji penyedia jenis Anda

Untuk memverifikasi bahwa jenis penyedia jenis Anda berfungsi seperti yang diharapkan:

Panggil penyedia jenis baru Anda di konfigurasi.
Deploy setiap koleksi yang disediakan oleh penyedia jenis untuk memastikan API berfungsi seperti yang diharapkan. Koleksi adalah resource API dari penyedia jenis yang ditetapkan.
Buat pembaruan pada setiap koleksi.
Hapus setiap koleksi.

Saat pengguna membuat instance jenis dari penyedia jenis Anda, mereka sebenarnya membuat permintaan ke Deployment Manager, bukan secara eksplisit ke API yang mendasarinya. Selanjutnya, Deployment Manager akan membuat permintaan dengan informasi yang disediakan untuk membuat permintaan ke API atas nama pengguna. Masalah paling umum yang mungkin Anda lihat adalah API tersebut memiliki properti yang sulit dikenali oleh Deployment Manager secara otomatis. Misalnya, beberapa API memerlukan properti yang hanya dapat diekstrak dari respons API. API lain mungkin menggunakan nama kolom yang sama dengan nilai yang berbeda, bergantung pada operasinya. Dalam kasus ini, Anda harus secara eksplisit memberi tahu Deployment Manager cara menangani skenario ini.

Jika API Anda memiliki salah satu karakteristik ini, gunakan pemetaan input untuk memperjelas ambiguitas untuk Deployment Manager.

Langkah selanjutnya

Pelajari cara memanggil penyedia jenis.
Membagikan penyedia jenis Anda dengan project lain.
Pelajari jenis lebih lanjut.
Baca tentang membuat konfigurasi.
Membuat deployment.
Pelajari lebih lanjut Opsi API Lanjutan.