設定進階 API 選項

本頁面說明如何設定類型提供者的進階設定選項，例如輸入對應和虛擬屬性。如要進一步瞭解類型，請參閱類型總覽一文。另外，如需類型提供者的相關詳情，請參閱 Deployment Manager 整合應用單頁指南。

如果您嘗試整合的 API 並未滿足 Deployment Manager 所定義的 API 需求條件，則可以使用輸入對應和虛擬屬性來解決不一致的問題。輸入對應可讓您針對模稜兩可的 API 參數提供明確對應。虛擬屬性則可讓您公開基礎 API 中不存在的任意屬性，以便簡化輸入並向使用者隱藏 API 的複雜性。

如要實作進階設定選項，您必須非常熟悉要為其建立類型提供者的 API。由於每個 API 可能差異甚多，因此本頁面僅提供一般指引和範例，而未提供特定 API 的相關指引。

事前準備

需要使用進階設定選項的常見情況

將屬性名稱重複用於不同的值

在某些 API 中，相同的屬性或參數名稱可能會重複用於不同方法，但是套用的值不同。舉例來說，API 可能會指定 name 參數用於建立資源 (POST 要求)，包含的值可能為 foo/bar；而用於更新要求 (PATCH 或 PUT) 的同一個 name 欄位，要求的值可能為 foo/bar/baz。

可從 API 回應推斷屬性值

某些 API 方法會要求提供當您向資源提交 GET 要求時，系統傳回由伺服器產生的值。例如，在變更資源時，API 可能需要 etag 參數來提交更新要求。提交每項變更要求後，etag 值都會變更，可讓您在提交資源更新要求前向資源執行 GET 要求，藉此取得目前的 etag 參數。

透過輸入對應，您就能指示 Deployment Manager 可從 API 資源中擷取 etag 欄位。使用者呼叫您在輸入對應中指定的方法時，Deployment Manager 就會自動執行 GET 要求來取得該值。

簡化使用者輸入

Deployment Manager 支援使用虛擬屬性；這類屬性是您可以透過 Deployment Manager 向使用者公開，以用於不同用途的任意屬性。 服務將虛擬屬性視為基礎 API 中不存在的屬性，但將其視為任意變數，您可以視需要將其中的值插入輸入對應。舉例來說，假設有一種 API 屬性必須採用 base64 編碼，才能將值傳送至基礎 API。您可以建立提醒使用者輸入純文字值的虛擬屬性，然後使用輸入對應對該值進行 base64 編碼，最後將結果提供給基礎 API，而且不必要求使用者提供 base64 編碼值。

指定進階選項

如要指定進階選項，請在建立類型提供者資源時提供 collectionOverrides 屬性，並視需求為每個 API 集合定義輸入對應或虛擬屬性。

舉例來說，您可以透過 gcloud CLI 提供使用 YAML 檔案的進階選項，並透過 type-providers create 要求提供 YAML 檔案。YAML 檔案範例看起來如下所示：

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]

此設定可以指示 Deployment Manager：

  • 針對 create 方法，查看資源主體中名為 emailAddress.displayName 的欄位，並將欄位值設為使用者在 Deployment Manager 設定中為 displayName 屬性輸入的值。因此，如果使用者按照以下方式設定：

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

    Deployment Manager 就會將 emailAddress.displayName 的值設為 John Doe。

  • 針對 update 方法，欄位位於資源路徑，而不是資源主體，但會套用相同的輸入對應。

指定輸入對應

輸入對應可以在某些 API 欄位中對應或插入資訊，以便 Deployment Manager 可以更流暢地與基礎 API 進行互動，進而減輕使用者必須瞭解細微 API 行為的負擔。

使用輸入對應可以簡化使用者與 API 的互動方式。例如，您可以使用輸入對應自動取得由伺服器產生的值 (像是指紋、ID 或 ETag)。這樣就能省去使用者在每次要進行更新時，必須對資源執行單獨的 get 要求的麻煩。

同樣地，您也能使用輸入對應處理模稜兩可或混淆的情況，其中相同的 API 欄位對於不同方法都有不同的值。 舉例來說，建立資源的要求可能需要使用者可以指定的 name 屬性；但是同一個 API 對於 update 方法則可能要求提供格式不同的 name 屬性。因此，您可以使用輸入對應來指示 Deployment Manager 每個 API 方法適用的值。

如要指定類型提供者的輸入對應，請提供 options.inputMappings 屬性。您可以定義適用於整個 API 的輸入對應，或是為每個集合特別提供輸入對應：

# 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]...
            ]
        }
    }
]

本語法各個重要部分說明如下。

集合

[SPECIFIC_COLLECTION] 是此輸入對應適用的 API 集合。例如，如果您為 Google Discovery 文件提供輸入對應 (例如 IAM Service Accounts API)，則相關的集合為 projects.serviceAccounts 和 projects.serviceAccountKeys。

對於使用 OpenAPI 規範的 API，集合路徑可能是 /example-collection/{name}。您可以前往 OpenAPI GitHub 存放區探索功能性 OpenAPI 範例。

欄位名稱

"fieldName" 是您要為其指定輸入對應的 API 屬性或性質，例如 "fieldName": "fingerprint", "fieldName": "etag" 等。

位置

API 屬性可以做為參數顯示在網址路徑，或是做為要求或回應內文的一部分。請指定輸入對應要套用的位置，例如網址 PATH 或要求 BODY。支援的值包括：

  • PATH
  • BODY
  • QUERY
  • HEADER

方法比對

您需要指定此輸入對應適用哪一些方法。您可以使用規則運算式來指定多種方法。例如：

"methodMatch":"^create$"

針對 OpenAPI 規範，方式如下：

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

值

請指定 Deployment Manager 應在此欄位中插入的值。 此欄位使用 JSONPath 標記法。 舉例來說，此輸入對應指示對於 name 欄位，Deployment Manager 應採用使用者提供的值，並將其插入到格式 projects/$.project/topics/$resource.properties.topic 中：

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

  • 使用 $.resource.properties.[VARIABLE] 時，您將值設定為使用者會在配置中設定的屬性。舉例來說，$.resource.properties.topic 的值即為使用者在配置中為屬性 topic 提供的值：

    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

  • 如要在提交 get 要求之後參照資源本身，請使用 $.resource.self.[VARIABLE]以更新要求為例，如要取得最新的指紋，您可以使用此語法指示 Deployment Manager 執行 get 並抓取相關值：

    {
  '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'
}

使用虛擬屬性

虛擬屬性為任意屬性，可以透過 Deployment Manager 向使用者公開。這些屬性不是基礎 API 的一部分，而是任意變數，可用於傳遞資訊或對使用者隱藏 API 的不一致處。此外，您也可以在輸入對應中參照虛擬屬性。

虛擬屬性採用 JSON 4 結構定義。請提供虛擬屬性，做為特定集合的 options 一部分：

"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": [
    ...
   ]
  }

在 YAML 定義檔案中，內容看起來如下所示：

- 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:
    ...

例如，假設有一種偽 API 專門產生電子郵件地址。此外，假設該 API 含有特定方法，能建立可接收 emailAddress.displayName 屬性的電子郵件。當使用者提交建立電子郵件地址的要求時，他們會提供與下方相似的要求：

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

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

現在，假設該 API 公開了一種更新電子郵件地址的方法，但是更新電子郵件的方法只需要 displayName 屬性，而非 email.displayName 屬性：

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

{
  "displayName": "josh"
}

當使用者使用這個類型提供者時，您會希望他們如何提供此值？您可以要求他們根據操作方式，指定不同的屬性：

# 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

或者，您可以建立採用相同值的虛擬屬性，無論操作方式為何，接著透過輸入對應將虛擬屬性對應到適用的 API 參數。對此範例來說，假設您定義了名為 displayName 的虛擬屬性，則輸入對應與以下類似：

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

具體而言，虛擬屬性是在本處定義：

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

此為使用者可判讀的格式：

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

現在，使用者可以將 displayName 指定為更新和建立要求的頂層屬性，而且 Deployment Manager 知道如何正確地對應到值。

# 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

後續步驟