Halaman ini diterjemahkan oleh Cloud Translation API.

Menambahkan API sebagai penyedia jenis

Halaman ini menjelaskan cara menambahkan API ke Google Cloud Deployment Manager sebagai penyedia jenis. Untuk mempelajari jenis dan penyedia 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 ditayangkan langsung oleh RESTful API yang mendukung Create, Read, Update, and Delete (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 menyiapkan layanan API Anda sendiri. Asumsinya adalah sudah ada API yang ingin Anda tambahkan, atau Anda sudah membuat API yang berjalan dan dapat diakses dari endpoint publik. Misalnya, untuk men-deploy contoh API menggunakan Google Cloud Endpoints, Anda dapat mengikuti Panduan Mulai Cepat 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-nya yang relevan.
Dokumen deskripsi: 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: Semua pemetaan input lanjutan atau opsi API.

Nama

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

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

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

Dokumen deskripsi

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.

Autentikasi

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 Google Cloud Endpoints, 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) dalam project yang sama dengan 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 di header Authorization. Tidak seperti di bagian kredensial sebelumnya, Anda harus memberikannya 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 lengkap, lihat contoh Cluster dan Jenis GKE.

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

(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 ke konfigurasi seperti dalam contoh berikut:

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

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

Opsi jenis lanjutan

API tertentu mungkin memiliki keunikannya sendiri yang menyulitkan Deployment Manager memetakan semua properti API ke Deployment Manager. Dalam skenario ideal, Anda menyediakan dokumen deskripsi dan Deployment Manager akan otomatis mengetahui jalur permintaan API dan properti API yang relevan tanpa perlu tindakan tambahan dari Anda. Untuk API yang lebih kompleks, Deployment Manager dapat memahami sebagian besar API, tetapi Anda mungkin perlu menentukan pemetaan input secara eksplisit 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 deskripsi, 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 ke jenis ini.
[URL] adalah URL yang sepenuhnya memenuhi syarat ke 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 memberikannya menggunakan tanda --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 akan menjadi:

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

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

Panggil penyedia jenis baru Anda dalam konfigurasi.
Deploy setiap koleksi yang disediakan oleh penyedia jenis untuk memastikan API berfungsi seperti yang diharapkan. Koleksi adalah resource API dari penyedia jenis yang ditentukan.
Buat pembaruan ke 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. Sebagai gantinya, Deployment Manager membuat permintaan dengan informasi yang diberikan untuk membuat permintaan ke API atas nama pengguna. Masalah paling umum yang mungkin Anda lihat adalah API memiliki properti yang sulit dikenali secara otomatis oleh Deployment Manager. 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 operasi. 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 mengklarifikasi ambiguitas untuk Deployment Manager.

Langkah selanjutnya

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