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 lebih lanjut penyedia jenis, baca Panduan Satu Halaman untuk Berintegrasi dengan Deployment Manager.

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

Penerapan opsi konfigurasi lanjutan memerlukan pemahaman mendalam tentang API yang digunakan untuk membuat penyedia jenis. Karena setiap API dapat sangat bervariasi dari API lainnya, halaman ini memberikan panduan dan contoh umum, tetapi tidak memberikan panduan API tertentu.

Sebelum memulai

Skenario umum yang memerlukan opsi konfigurasi lanjutan

Nama properti digunakan kembali dengan nilai yang berbeda

Di API tertentu, nama properti atau parameter yang sama dapat digunakan kembali dalam metode yang berbeda, tetapi dengan nilai yang berbeda. Misalnya, API dapat menentukan bahwa parameter name untuk membuat resource (permintaan POST), mungkin memiliki nilai foo/bar, sementara 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 memutasi resource. Nilai etag berubah setelah setiap permintaan perubahan, jadi 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 ke pengguna melalui Deployment Manager untuk berbagai penggunaan. Perlakukan properti virtual sebagai properti yang tidak ada di API pokok, tetapi merupakan variabel arbitrer yang nilainya dapat Anda masukkan sesuai kebutuhan dalam pemetaan input. Misalnya, bayangkan ada properti API yang harus dienkode base64 sebelum nilainya dikirim ke API yang mendasarinya. Daripada meminta pengguna memberikan nilai dalam encoding base64, Anda dapat membuat properti virtual yang meminta pengguna untuk memberikan nilai teks biasa, lalu mengenkode nilai dengan base64 menggunakan pemetaan input, dan terakhir, memberikan hasil ke API yang mendasarinya.

Menentukan opsi lanjutan

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

Misalnya, dengan menggunakan gcloud CLI, Anda dapat memberikan opsi lanjutan menggunakan file YAML dan menyediakan file YAML dengan permintaan type-providers create Anda. 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 di isi resource dan tetapkan nilai kolom tersebut ke input pengguna untuk properti displayName dalam konfigurasi Deployment Manager. Jadi, jika pengguna menyetel konfigurasinya 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 berada di jalur resource, bukan di isi resource, tetapi pemetaan input yang sama diterapkan.

Menentukan pemetaan input

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

Gunakan pemetaan input untuk menyederhanakan cara pengguna berinteraksi dengan API. Misalnya, Anda dapat menggunakan pemetaan input untuk mendapatkan nilai yang dihasilkan server secara otomatis, seperti sidik jari, ID, atau etag. Hal ini membuat pengguna tidak perlu melakukan permintaan get terpisah pada resource setiap kali mereka ingin melakukan pembaruan.

Demikian pula, Anda juga dapat menggunakan pemetaan input untuk menangani situasi yang ambigu atau membingungkan ketika 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 mana 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 seluruh 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 kumpulan API yang menerapkan pemetaan input ini. Misalnya, jika Anda memberikan pemetaan input untuk dokumen penemuan Google, seperti IAM Service Accounts API, kumpulan yang relevan adalah projects.serviceAccounts dan projects.serviceAccountKeys.

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

Nama kolom

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

Location

Properti API dapat muncul sebagai parameter di jalur URL, atau sebagai bagian dari isi permintaan atau respons. Tentukan tempat penerapan pemetaan input ini, 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 regex untuk menentukan beberapa metode. Contoh:

"methodMatch":"^create$"

Untuk spesifikasi OpenAPI, Anda dapat melakukan:

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

Nilai

Tentukan nilai yang harus disisipkan 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 diberikan pengguna dan menyisipkannya 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 konfigurasi mereka. 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 Anda ingin mendapatkan sidik jari terbaru, Anda dapat menggunakan sintaksis ini untuk memberi tahu Deployment Manager agar melakukan 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 ekspos ke 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, ini akan terlihat seperti:

- 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 membuat alamat email. Misalkan API 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 mengharapkan pengguna memberikan nilai ini saat mereka menggunakan penyedia jenis ini? Anda dapat meminta mereka untuk menentukan properti secara berbeda, bergantung pada operasi:

# 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 mengambil nilai yang sama, terlepas dari operasinya, lalu menggunakan pemetaan input untuk memetakan properti virtual ke parameter API yang sesuai. Untuk contoh ini, asumsikan Anda telah menentukan properti virtual bernama displayName. Pemetaan input Anda kemudian dapat 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 ditentukan 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 menentukan displayName sebagai properti tingkat 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 berikutnya