Erweiterte API-Optionen festlegen

Auf dieser Seite wird beschrieben, wie Sie erweiterte Konfigurationsoptionen, wie Eingabezuordnungen und virtuelle Eigenschaften, für Typanbieter einrichten. Weitere Informationen über Typen finden Sie unter Typenübersicht. Weitere Informationen über Typanbieter finden Sie in der Kurzanleitung zur Integration in Deployment Manager.

Wenn Sie versuchen, eine API zu integrieren, die die von Deployment Manager definierten API-Anforderungen nicht erfüllt, können Sie Eingabezuordnungen und virtuelle Eigenschaften verwenden, um diese Inkonsistenzen zu lösen. Mit Eingabezuordnungen stellen Sie ausdrückliche Zuordnungen zu API-Parametern her, wodurch Sie Unklarheiten beseitigen. Mit virtuellen Eigenschaften zeigen Sie beliebige Eigenschaften an, die nicht in den zugrunde liegenden APIs. vorhanden sind. Auf diese Weise können Sie die Eingabe vereinfachen und komplexe API-Zusammenhänge vor Ihren Nutzern verbergen.

Die Implementierung erweiterter Konfigurationsoptionen erfordert genaue Kenntnisse der API, für die Sie den Typanbieter erstellen. Da jede API stark von anderen APIs abweichen kann, enthält diese Seite allgemeine Anleitungen und Beispiele, bietet jedoch keine Anleitungen für spezifische APIs.

Vorbereitung

Anforderungen für erweiterte Konfigurationsoptionen

Eigenschaftsnamen mit anderen Werten wiederverwenden

In bestimmten APIs wird der gleiche Eigenschafts- oder Parametername in verschiedenen Methoden, aber mit unterschiedlichen Werten wiederverwendet. Beispiel: Eine API verwendet den Parameter name zum Erstellen einer Ressource mit einer POST-Anfrage. Der Wert des Parameters könnte foo/bar lauten. Gleichzeitig kann dasselbe name-Feld für eine Aktualisierungsanfrage mit PATCH oder PUT den Wert foo/bar/baz erfordern.

Eigenschaftswerte aus der API-Antwort ableiten

Bestimmte API-Methoden erfordern einen vom Server generierten Wert, der zurückgegeben wird, wenn Sie eine GET-Anfrage an die Ressource stellen. Beispielsweise benötigt eine API möglicherweise einen etag-Parameter, um Aktualisierungsanfragen beim Mutieren einer Ressource vorzunehmen. Der Wert etag ändert sich nach jeder Mutationsanfrage, sodass Sie den aktuellen etag-Parameter mit einer GET-Anfrage an die Ressource erhalten, bevor Sie die Anfrage zum Aktualisieren der Ressource stellen.

Mit Eingabezuordnungen legen Sie fest, dass Deployment Manager das Feld etag von der API-Ressource abrufen kann. Deployment Manager führt automatisch eine GET-Anfrage aus, um diesen Wert zu erhalten, wenn ein Nutzer die Methode aufruft, die Sie in den Eingabezuordnungen angegeben haben.

Nutzereingabe vereinfachen

Deployment Manager unterstützt virtuelle Eigenschaften, die beliebige Eigenschaften sind, und die Sie Ihren Nutzern über Deployment Manager für verschiedene Zwecke anzeigen können. Behandeln Sie virtuelle Eigenschaften wie Eigenschaften, die nicht in der zugrunde liegenden API vorhanden sind, aber wie beliebige Variablen funktionieren, deren Werte Sie bei Bedarf in Ihre Eingabezuordnungen einfließen lassen können. Beispiel: Angenommen, es gibt eine API-Eigenschaft, die Base64-codiert sein muss, bevor der Wert an die zugrunde liegende API gesendet wird. Anstatt Ihre Nutzer aufzufordern, einen Base64-codierten Wert bereitzustellen, können Sie eine virtuelle Eigenschaft erstellen, die den Nutzer zur Eingabe von reinem Text auffordert. Die Base64-Codierung des Wertes wird dann über eine Eingabezuordnung gelöst. Anschließend wird der korrekt codierte Wert an die zugrunde liegende API übergeben.

Erweiterte Optionen festlegen

Um erweiterte Optionen anzugeben, müssen Sie die Eigenschaft collectionOverrides bereitstellen, wenn Sie Ihre Typanbieter-Ressource erstellen. Definieren Sie dann je nach Erfordernis Eingabezuordnungen oder virtuelle Eigenschaften für jede API-Sammlung.

Beispiel: Sie können mit dem gcloud-Tool erweiterte Optionen mithilfe einer YAML-Datei bereitstellen. Dann liefern Sie die YAML-Datei mit der type-providers create-Anfrage. Eine YAML-Datei kann beispielsweise wie folgt aussehen:

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]

Diese Konfigurationen weisen Deployment Manager zu Folgendem an:

  • Suche für die create-Methode nach einem Feld namens emailAddress.displayName im Ressourcentext und setze in der Deployment Manager-Konfiguration den Wert dieses Feldes auf die Nutzereingabe für die displayName-Eigenschaft. Wenn ein Nutzer also die Konfiguration wie folgt festlegt:

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

    setzt Deployment Manager den Wert für emailAddress.displayName auf John Doe.

  • Für die update-Methode befindet sich das Feld im Ressourcenpfad und nicht im Ressourcentext. Dennoch wird dieselbe Eingabezuordnung angewendet.

Eingabezuordnungen festlegen

Mithilfe einer Eingabezuordnung können Sie Informationen bestimmten API-Feldern zuordnen oder hinzufügen, sodass Deployment Manager nahtlos mit der zugrunde liegenden API interagieren kann. Auf diese Weise werden Ihre Nutzer entlastet und müssen das komplizierte Verhalten der API nicht kennen.

Verwenden Sie Eingabezuordnungen dazu, die Interaktion zwischen Nutzer und API zu vereinfachen. Sie können Eingabezuordnungen beispielsweise dazu verwenden, automatisch vom Server generierte Werte zu erhalten, wie etwa Fingerabdrücke, IDs oder ETags. Dies erspart dem Nutzer die Mühe, jedes Mal eine get-Anfrage an die Ressource zu stellen, wenn eine Aktualisierung durchgeführt werden soll.

In ähnlicher Weise können Sie Eingabezuordnungen dazu verwenden, mehrdeutige oder verwirrende Situationen abzufangen, in denen das gleiche API-Feld unterschiedliche Werte für verschiedene Methoden verwendet. Beispiel: Eine Anfrage zur Erstellung einer Ressource kann die Eigenschaft name erfordern, die der Nutzer festlegen kann. Aber dieselbe API erfordert möglicherweise eine name-Eigenschaft in einem anderen Format für update-Methoden. Sie können Eingabezuordnungen verwenden, um Deployment Manager anzuweisen, welcher Wert für die jeweilige API-Methode erforderlich ist.

Eingabezuordnungen für einen Typanbieter legen Sie mit der options.inputMappings-Eigenschaft fest. Sie können Eingabezuordnungen definieren, die für die gesamte API gelten, oder Sie können explizite Eingabezuordnungen für jede Sammlung bereitstellen:

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

Jeder wichtige Teil dieser Syntax wird nachstehend beschrieben.

Sammlung

[SPECIFIC_COLLECTION] ist die API-Sammlung, für die diese Eingabezuordnung gilt. Wenn Sie zum Beispiel Eingabezuordnungen für ein Google Discovery-Dokument bereitstellen, wie die IAM Service Accounts API, sind die relevanten Sammlungen projects.serviceAccounts und projects.serviceAccountKeys.

Für eine API, die eine OpenAPI-Spezifikation verwendet, könnte der Sammlungspfad /example-collection/{name} sein. Im OpenAPI GitHub-Repository steht ein OpenAPI-Beispiel für Sie zur Erkundung bereit.

Feldname

"fieldName" ist das API-Attribut oder die Eigenschaft, für die Sie eine Eingabezuordnung festlegen können. Beispiel: "fieldName": "fingerprint", "fieldName": "etag" und so weiter.

Ort

API-Eigenschaften können entweder als Parameter im URL-Pfad oder als Teil des Anfrage- oder Antworttextes angezeigt werden. Geben Sie an, wo diese Eingabezuordnung gelten soll, z. B. den Speicherort PATH einer URL oder den BODY-Teil einer Anfrage. Unterstützte Werte sind:

  • PATH
  • BODY
  • QUERY
  • HEADER

Methodenentsprechungen

Geben Sie an, auf welche Methoden diese Eingabezuordnungen angewendet werden. Verwenden Sie reguläre Ausdrücke, um mehrere Methoden anzugeben. Beispiel:

"methodMatch":"^create$"

Für OpenAPI-Spezifikationen geben Sie Folgendes ein:

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

Wert

Geben Sie den Wert an, den Deployment Manager für dieses Feld einfügen soll. Dieses Feld verwendet die JSONPath-Notation. Beispiel: Diese Eingabezuordnung besagt, dass Deployment Manager für das Feld name den vom Nutzer bereitgestellten Wert verwenden und im Format projects/$.project/topics/$resource.properties.topic einfügen soll:

"inputMappings":[
{
  "fieldName":"name",
  "location":"PATH",
  "methodMatch":"^post$",
  "value":"concat(\"projects/\", $.project, \"/topics/\", $.resource.properties.topic)"
}...
  • Wenn Sie $.resource.properties.[VARIABLE] verwenden,legen Sie den Wert einer Eigenschaft fest, die ein Benutzer in der Konfiguration angibt. Beispiel: Für $.resource.properties.topic wird der vom Nutzer für die topic-Eigenschaft in der Konfiguration bereitgestellte Wert verwendet:

    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
    
  • Um die Ressource selbst nach einer get-Anfrage zu referenzieren, verwenden Sie $.resource.self.[VARIABLE]. Beispiel: Wenn Sie für Aktualisierungsanfragen den neuesten Fingerabdruck erhalten möchten, können Sie diese Syntax verwenden. Damit weisen Sie Deployment Manager an, eine get-Anfrage auszuführen und den Wert zu verwenden:

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

Virtuelle Eigenschaften verwenden

Virtuelle Eigenschaften sind beliebige Eigenschaften, die Sie für Ihre Nutzer über Deployment Manager anzeigen können. Diese Eigenschaften sind nicht Teil der zugrunde liegenden API, sondern beliebige Variablen, die sich zur Übergabe von Informationen oder zum Verbergen von Inkonsistenzen der API vor Ihren Nutzern verwenden lassen. Sie können auch in Ihren Eingabezuordnungen auf virtuelle Eigenschaften referenzieren.

Virtuelle Eigenschaften folgen dem JSON 4-Schema. Stellen Sie virtuelle Eigenschaften als Teil der options für eine bestimmte Sammlung bereit:

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

In einer YAML-Definitionsdatei würde das wie folgt aussehen:

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

Angenommen, Sie haben eine Pseudo-API, die E-Mail-Adressen generiert. Weiter angenommen, die API verfügt über eine Methode zum Erstellen von E-Mails, die die Eigenschaft email.displayName verwenden. Wenn ein Nutzer eine Anfrage zum Erstellen einer E-Mail-Adresse stellt, könnte diese wie folgt aussehen:

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

{
  "email": {
    "displayName": "john"
  }
}

Nun nehmen wir an, die API bietet eine Möglichkeit, die E-Mail-Adresse zu aktualisieren, aber die Methode zum Aktualisieren der E-Mail-Adresse erfordert die Eigenschaft displayName und nicht die Eigenschaft email.displayName:

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

{
  "displayName": "josh"
}

Wie soll Ihr Nutzer diesen Wert angeben, wenn er diesen Typanbieter verwendet? Sie könnten ihn bitten, die Eigenschaft je nach Vorgang unterschiedlich anzugeben:

# 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

Alternativ könnten Sie eine virtuelle Eigenschaft erstellen, die unabhängig vom Vorgang den gleichen Wert verwendet und dann die Eingabezuordnung nutzt, um die virtuelle Eigenschaft dem entsprechenden API-Parameter zuzweisen. In diesem Beispiel wird davon ausgegangen, dass Sie eine virtuelle Eigenschaft namens displayName definiert haben. Ihre Eingabezuordnungen könnten dann so aussehen:

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

Die virtuelle Eigenschaft wird hier definiert:

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

Im für Menschen lesbaren Format:

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

Jetzt können Ihre Nutzer displayName als übergeordnete Eigenschaft für die Aktualisierungs- und die Erstellungsanfrage angeben. Deployment Manager wird genau wissen, wie die Werte korrekt zuzuordnen sind.

# 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

Nächste Schritte

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Cloud Deployment Manager-Dokumentation