Menetapkan Opsi API Lanjutan

Halaman ini menjelaskan cara menyiapkan opsi konfigurasi lanjutan, seperti pemetaan input dan properti virtual, untuk penyedia jenis. Untuk mempelajari jenis lebih lanjut, baca Ringkasan Jenis. Untuk mempelajari penyedia jenis lebih lanjut, baca Panduan Satu Halaman untuk Berintegrasi dengan Deployment Manager.

Jika Anda mencoba mengintegrasikan API yang tidak memenuhi persyaratan API yang ditetapkan oleh Deployment Manager, Anda dapat menggunakan pemetaan input dan properti virtual untuk membantu mengatasi inkonsistensi ini. Pemetaan input memungkinkan Anda memberikan pemetaan eksplisit untuk parameter API jika ada ambiguitas dan properti virtual memungkinkan Anda mengekspos properti arbitrer yang tidak ada di API dasar sehingga Anda dapat menyederhanakan input dan menyembunyikan kompleksitas API dari pengguna.

Menerapkan opsi konfigurasi lanjutan memerlukan pemahaman yang mendalam dengan API yang Anda buatkan penyedia jenis. Karena setiap API dapat sangat bervariasi dari yang lain, halaman ini memberikan panduan dan contoh umum, tetapi tidak memberikan panduan API yang spesifik.

Sebelum memulai

Skenario umum yang memerlukan opsi konfigurasi lanjutan

Nama properti digunakan kembali dengan nilai yang berbeda

Dalam API tertentu, properti atau nama parameter yang sama dapat digunakan kembali dalam metode yang berbeda, tetapi dengan nilai yang berbeda. Misalnya, API mungkin menentukan bahwa parameter name untuk membuat resource (permintaan POST), mungkin memiliki nilai foo/bar, sedangkan kolom name yang sama untuk permintaan update (PATCH atau PUT) mungkin memerlukan nilai foo/bar/baz.

Nilai properti dapat disimpulkan dari respons API

Metode API tertentu memerlukan nilai yang dihasilkan server yang ditampilkan saat Anda membuat permintaan GET ke resource. Misalnya, API mungkin memerlukan parameter etag untuk membuat permintaan update saat mengubah resource. Nilai etag berubah setelah setiap permintaan mutasi, sehingga Anda mendapatkan parameter etag saat ini dengan melakukan permintaan GET ke resource, sebelum membuat permintaan untuk memperbarui resource.

Dengan menggunakan pemetaan input, Anda dapat memberi tahu Deployment Manager bahwa kolom etag dapat diambil dari resource API. Deployment Manager otomatis melakukan permintaan GET untuk mendapatkan nilai ini saat pengguna memanggil metode yang Anda tentukan dalam pemetaan input.

Menyederhanakan input pengguna

Deployment Manager mendukung properti virtual yang merupakan properti arbitrer yang dapat Anda ekspos kepada pengguna melalui Deployment Manager untuk berbagai penggunaan. Perlakukan properti virtual sebagai properti yang tidak ada pada API yang mendasarinya, tetapi merupakan variabel arbitrer yang nilainya dapat Anda masukkan sesuai kebutuhan dalam pemetaan input. Misalnya, bayangkan ada properti API yang harus dienkode dengan base64 sebelum nilai dikirim ke API yang mendasarinya. Daripada meminta pengguna memberikan nilai dalam encoding base64, Anda dapat membuat properti virtual yang meminta nilai teks biasa kepada pengguna, lalu mengenkode base64 nilai dengan pemetaan input, dan terakhir, menyediakan hasilnya ke API yang mendasarinya.

Menentukan opsi lanjutan

Untuk menentukan opsi lanjutan, sediakan properti collectionOverrides saat membuat resource Penyedia Jenis, dan tentukan pemetaan input atau properti virtual untuk setiap koleksi API sesuai kebutuhan Anda.

Misalnya, dengan gcloud CLI, Anda dapat memberikan opsi lanjutan menggunakan file YAML dan menyediakan file YAML dengan permintaan type-providers create. Contoh file YAML 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
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Konfigurasi ini memberi tahu Deployment Manager:

  • Untuk metode create, cari kolom bernama emailAddress.displayName dalam isi resource dan tetapkan nilai kolom tersebut ke input pengguna untuk properti displayName dalam konfigurasi Deployment Manager. Jadi, jika pengguna menetapkan konfigurasi seperti ini:

     resources:
 - name: example
   type: myproject/emailAddress:/emailAddresses/v1beta/people
   properties:
   - displayName: John Doe
     ...

    Deployment Manager akan menetapkan nilai untuk emailAddress.displayName ke John Doe.

  • Untuk metode update, kolom ini berada di jalur resource, bukan isi resource, tetapi pemetaan input yang sama diterapkan.

Menentukan pemetaan input

Pemetaan input memungkinkan Anda memetakan atau memasukkan informasi untuk kolom API tertentu, sehingga Deployment Manager dapat berinteraksi secara lebih lancar dengan API yang mendasarinya, sehingga mengurangi beban pengguna untuk memahami perilaku API yang samar.

Gunakan pemetaan input untuk menyederhanakan cara pengguna berinteraksi dengan API. Misalnya, Anda dapat menggunakan pemetaan input untuk otomatis mendapatkan nilai yang dihasilkan server, seperti sidik jari, ID, atau etag. Dengan demikian, pengguna tidak perlu lagi direpotkan dalam melakukan permintaan get terpisah pada resource setiap kali mereka ingin melakukan update.

Demikian pula, Anda juga dapat menggunakan pemetaan input untuk menangani situasi yang ambigu atau membingungkan saat kolom API yang sama memiliki nilai yang berbeda untuk metode yang berbeda. Misalnya, permintaan untuk membuat resource mungkin memerlukan properti name yang dapat ditentukan pengguna, tetapi API yang sama mungkin memerlukan properti name dalam format yang berbeda untuk metode update. Anda dapat menggunakan pemetaan input untuk memberi tahu Deployment Manager nilai yang sesuai untuk setiap metode API.

Untuk menentukan pemetaan input bagi penyedia jenis, berikan properti options.inputMappings. Anda dapat menentukan pemetaan input yang berlaku untuk keseluruhan API atau Anda dapat secara eksplisit memberikan pemetaan input untuk setiap koleksi:

# Input mappings for the entire API
"options": {
  "inputMappings": [
      {
          "fieldName": "[NAME]",
          "location":  "[PATH | BODY | QUERY | HEADER]",
          "methodMatch": "[REGEX_MATCHING_CERTAIN_METHODS]",
          "value": "[VALUE_TO_INJECT]"
      },
      {
          "fieldName": "[NAME]",
          "location":  "[PATH | BODY | QUERY | HEADER]",
          "methodMatch": "[REGEX_MATCHING_CERTAIN_METHODS]",
          "value": "[VALUE_TO_INJECT]"
      }
   ]
},
# Input mappings for specific collections
"collectionOverrides": [
    {
        "collection": "[SPECIFIC_COLLECTION]",
        "options": {
            "inputMappings": [
                {
                    "fieldName": "[NAME]",
                    "location": "[PATH | BODY | QUERY | HEADER]",
                    "methodMatch": "[REGEX_MATCHING_CERTAIN_METHODS]",
                    "value": "[VALUE_TO_INJECT]"
                },
                {
                    "fieldName": "[NAME]",
                    "location": "[PATH | BODY]",
                    "methodMatch": "[REGEX_MATCHING_CERTAIN_METHODS]",
                    "value": "[VALUE_TO_INJECT]"
                },
                ...[additional fields if necessary]...
            ]
        }
    }
]

Setiap bagian penting dari sintaksis ini dijelaskan di bawah.

Pengumpulan

[SPECIFIC_COLLECTION] adalah koleksi API yang menerapkan pemetaan input ini. Misalnya, jika Anda memberikan pemetaan input untuk dokumen Google Discovery, seperti IAM Service Accounts API, koleksi yang relevan adalah projects.serviceAccounts dan projects.serviceAccountKeys.

Untuk API yang menggunakan spesifikasi OpenAPI, jalur pengumpulannya mungkin adalah /example-collection/{name}. Anda dapat mempelajari contoh OpenAPI yang fungsional di repositori GitHub OpenAPI.

Nama kolom

"fieldName" adalah atribut atau properti API yang pemetaan inputnya ingin Anda tentukan. Misalnya, "fieldName": "fingerprint", "fieldName": "etag" dan sebagainya.

Lokasi

Properti API dapat muncul sebagai parameter di jalur URL, atau sebagai bagian dari isi permintaan atau respons. Tentukan tempat pemetaan input ini akan diterapkan, seperti URL PATH atau permintaan BODY sebagai lokasi. Nilai yang didukung meliputi:

  • PATH
  • BODY
  • QUERY
  • HEADER

Pencocokan metode

Tentukan metode yang diterapkan pemetaan input ini. Gunakan ekspresi reguler untuk menentukan beberapa metode. Contoh:

"methodMatch":"^create$"

Untuk spesifikasi OpenAPI, Anda dapat melakukan:

"methodMatch: ^(put|get|delete|post)$"

Nilai

Tentukan nilai yang harus dimasukkan Deployment Manager untuk kolom ini. Kolom ini menggunakan notasi JSONPath. Misalnya, pemetaan input ini menyatakan bahwa untuk kolom name, Deployment Manager harus mengambil nilai yang disediakan pengguna dan memasukkannya ke dalam format projects/$.project/topics/$resource.properties.topic:

"inputMappings":[
{
  "fieldName":"name",
  "location":"PATH",
  "methodMatch":"^post$",
  "value":"concat(\"projects/\", $.project, \"/topics/\", $.resource.properties.topic)"
}...

  • Saat menggunakan $.resource.properties.[VARIABLE], Anda menetapkan nilai ke properti yang akan ditetapkan pengguna dalam konfigurasinya. Misalnya, untuk $.resource.properties.topic, nilainya akan berupa nilai yang diberikan pengguna untuk properti topic dalam konfigurasinya:

    resources:
- name: example
  type: example-type-provider:collectionA
  properties:
    topic: history # The value of "history" would be used for the `name` parameter because of the input mapping above

  • Untuk mereferensikan resource itu sendiri setelah permintaan get, gunakan $.resource.self.[VARIABLE]. Misalnya, untuk permintaan update, jika ingin mendapatkan sidik jari terbaru, Anda dapat menggunakan sintaksis ini untuk memberi tahu Deployment Manager agar menjalankan get dan mengambil nilainya:

    {
  'fieldName': 'fingerprint',
  'location': 'BODY',
  'methodMatch': '^(put)$',
  # self represents the resource by doing a GET on it.
  # This mappings gets latest fingerprint on the request.
  # Final PUT Body will be
  # {
  #   "name": "my-resource-name",
  #   "fingerprint": "<server generated fingerprint>"
  # }
  'value': '$.resource.self.fingerprint'
}

Menggunakan properti virtual

Properti virtual adalah properti arbitrer yang dapat Anda tampilkan kepada pengguna melalui Deployment Manager. Properti ini bukan bagian dari API yang mendasarinya, tetapi merupakan variabel arbitrer yang dapat digunakan untuk meneruskan informasi atau menyembunyikan inkonsistensi API dari pengguna Anda. Anda juga dapat mereferensikan properti virtual dalam pemetaan input.

Properti virtual mengikuti skema JSON 4. Berikan properti virtual sebagai bagian dari options untuk koleksi tertentu:

"collection": "[SPECIFIC_COLLECTION]",
  "options": {
   "virtualProperties": "schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  [PROPERTY]:\n    type: [DATA_TYPE]\n  [ANOTHER_PROPERTY]:\n    type: [ANOTHER_DATA_TYPE]n"
   "inputMappings": [
    ...
   ]
  }

Dalam file definisi YAML, akan terlihat seperti ini:

- collection: projects.serviceAccounts
  options:
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        a-property:
          type : string
        b-property:
          type : string
      required:
      - a-property
      - b-property
    inputMappings:
    ...

Misalnya, pertimbangkan API palsu yang menghasilkan alamat email. Anggaplah API tersebut memiliki metode untuk membuat email yang menggunakan properti emailAddress.displayName. Saat pengguna membuat permintaan untuk membuat alamat email, mereka akan memberikan permintaan seperti berikut:

POST https://example.com/emailAddresses/v1beta/people/

{
  "emailAddress": {
    "displayName": "john"
  }
}

Sekarang, misalkan API mengekspos cara untuk memperbarui alamat email, tetapi metode untuk memperbarui email hanya memerlukan properti displayName, bukan properti email.displayName:

POST https://example.com/emailAddresses/v1beta/people/john

{
  "displayName": "josh"
}

Bagaimana Anda memperkirakan pengguna akan memberikan nilai ini saat mereka menggunakan penyedia jenis ini? Anda dapat meminta mereka untuk menentukan properti secara berbeda bergantung pada operasinya:

# Creating an email
resources:
- name: example-config
  type: projects/test-project:emailAddresses
  properties:
    emailAddress:
      displayName: john

# Updating an email
resources:
- name: example-config
  type: projects/test-project:emailAddresses
  properties:
    displayName: john

Atau, Anda dapat membuat properti virtual yang menggunakan nilai yang sama, terlepas dari operasinya, lalu menggunakan pemetaan input untuk memetakan properti virtual ke parameter API yang sesuai. Untuk contoh ini, anggap Anda menentukan properti virtual bernama displayName. Pemetaan input Anda akan terlihat seperti ini:

{
    "collectionOverrides":[
      {
        "collection":"emailAddresses",
        "options":{
          "inputMappings":[
            {
              "fieldName":"emailAddress.displayName",
              "location":"BODY",
              "methodMatch":"^create$",
              "value":"$.resource.properties.displayName"
            },
            {
              "fieldName":"displayName",
              "location":"BODY",
              "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"
        }
      }
    ],
    "descriptorUrl":"https://example.com/emailAddresses/v1beta/",
    "options":{
      "nameProperty":""
    }
}

Secara khusus, properti virtual didefinisikan di sini:

"virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"

Dalam format yang dapat dibaca manusia:

"virtualProperties":
  "schema: http://json-schema.org/draft-04/schema#\n
   type: object\n
   properties:\n
     displayName:\n
     - type: string\n
   required:\n
   - displayName\n"

Sekarang, pengguna Anda dapat menetapkan displayName sebagai properti level teratas untuk permintaan update dan pembuatan, dan Deployment Manager akan mengetahui cara memetakan nilai dengan benar.

# Creating an email
resources:
- name: example-config
  type: projects/test-project:emailAddresses
  properties:
    displayName: john

# Updating an email
resources:
- name: example-config
  type: projects/test-project:emailAddresses
  properties:
    displayName: john

Langkah selanjutnya