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 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 eksplisit jika ada ambiguitas dan properti virtual memungkinkan Anda mengekspos properti arbitrer yang tidak ada di API yang mendasarinya sehingga Anda dapat menyederhanakan input dan menyembunyikan kompleksitas API dari pengguna.

Menerapkan opsi konfigurasi lanjutan memerlukan pemahaman mendalam tentang API yang Anda gunakan untuk membuat penyedia jenis. Karena setiap API dapat sangat berbeda 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 mungkin menentukan bahwa parameter name untuk membuat resource (permintaan POST) mungkin memiliki nilai foo/bar, sedangkan kolom name yang sama untuk permintaan pembaruan (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 pembaruan 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 di 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 untuk memberikan nilai dalam encoding base64, Anda dapat membuat properti virtual yang meminta pengguna untuk memasukkan nilai teks biasa, lalu mengenkode nilai tersebut dalam base64 dengan pemetaan input, dan terakhir, memberikan hasilnya 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 dalam isi resource dan tetapkan nilai kolom tersebut ke input pengguna untuk properti displayName dalam konfigurasi Deployment Manager. Jadi, jika pengguna menetapkan 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 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 dengan API yang mendasarinya dengan lebih lancar, sehingga meringankan beban pengguna untuk memahami perilaku API yang halus.

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. Hal ini menghemat pengguna dari masalah melakukan permintaan get terpisah pada resource setiap kali mereka ingin melakukan update.

Demikian pula, Anda juga dapat menggunakan pemetaan input untuk menangani situasi 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 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.

Koleksi

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

Untuk API yang menggunakan spesifikasi OpenAPI, jalur koleksi mungkin adalah /example-collection/{name}. Anda dapat menjelajahi contoh OpenAPI fungsional 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 pemetaan input ini berlaku, seperti URL PATH atau permintaan BODY sebagai lokasi. Nilai yang didukung meliputi:

  • PATH
  • BODY
  • QUERY
  • HEADER

Kecocokan 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 untuk 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 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, tampilannya akan 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. Mari kita asumsikan bahwa API memiliki metode untuk membuat email yang menggunakan properti emailAddress.displayName. Saat pengguna membuat permintaan untuk membuat alamat email, mereka memberikan permintaan seperti ini:

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 menggunakan nilai yang sama, terlepas dari operasinya, lalu menggunakan pemetaan input untuk memetakan properti virtual ke parameter API yang sesuai. Untuk contoh ini, asumsikan Anda 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 pembaruan 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