Menambahkan API sebagai penyedia jenis

Halaman ini menjelaskan cara menambahkan API ke Google Cloud Deployment Manager sebagai penyedia jenis. Untuk mempelajari lebih lanjut jenis dan penyedia jenis, 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, dan Delete (CRUD).

Jika ingin menggunakan API yang tidak disediakan secara otomatis 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 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:

• Name: Nama penyedia jenis yang diinginkan. Anda akan menggunakan nama ini untuk mereferensikan jenis dan resource API yang relevan.
• Dokumen deskriptor: URL dokumen deskriptor untuk jenis. Dokumen yang didukung mencakup dokumen Google Discovery atau spesifikasi OpenAPI 1.2.
• Autentikasi: Kredensial autentikasi 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 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 di template berikutnya seperti ini:

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

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

Dokumen deskriptor

Dokumen deskriptor 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 Penemuan.

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 Endpoints, Anda dapat menggunakan header Authorization untuk menyediakan token akses dari akun layanan project. Google Cloud

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 memberikan ini 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 huruf lanjutan

API tertentu mungkin memiliki keunikan yang menyulitkan Deployment Manager memetakan semua properti API ke Deployment Manager. Dalam skenario ideal, Anda menyediakan dokumen deskriptor dan Deployment Manager akan otomatis menentukan 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 lebih lanjut pemetaan input, 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 beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

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]

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

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

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"
    }
  }
}

Menguji penyedia font Anda

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

1. Panggil penyedia jenis baru Anda dalam konfigurasi.
2. Deploy setiap koleksi yang disediakan oleh penyedia jenis untuk memastikan API berfungsi seperti yang diharapkan. Kumpulan adalah resource API dari penyedia jenis yang ditentukan.
3. Lakukan pembaruan pada setiap koleksi.
4. 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 menyusun 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 ciri ini, gunakan pemetaan input untuk memperjelas ambiguitas bagi Deployment Manager.

Langkah berikutnya

• Pelajari cara memanggil penyedia huruf.
• Bagikan penyedia huruf Anda dengan project lain.
• Pelajari jenis lebih lanjut.
• Baca artikel tentang membuat konfigurasi.
• Buat deployment.
• Pelajari lebih lanjut Opsi API Lanjutan.

^{© 2016 Swagger. Semua hak dilindungi undang-undang.}