Impostazione delle opzioni avanzate dell'API

Questa pagina descrive come configurare opzioni di configurazione avanzate, come mappature di input e proprietà virtuali, per i provider di tipi. Per scoprire di più su di lettura, leggi Panoramica dei tipi. Per scoprire di più sui fornitori di tipi, consulta la guida di una pagina per l'integrazione con Deployment Manager.

Se stai tentando di integrare un'API che non soddisfa le Requisiti delle API definiti da Deployment Manager, puoi utilizzare le mappature di input e le proprietà virtuali per risolvere queste incoerenze. Le mappature degli input ti consentono di fornire informazioni mappature dei parametri API in cui c'è ambiguità e proprietà virtuali si espone proprietà arbitrarie che non esistono nelle API sottostanti, può semplificare l'input e nascondere le complessità dell'API agli utenti.

L'implementazione di opzioni di configurazione avanzate richiede una conoscenza approfondita dell'API per la quale stai creando il provider di tipi. Poiché ogni API può variare molto da altre, questa pagina fornisce indicazioni generali ed esempi, ma non indicazioni specifiche per le API.

Prima di iniziare

Scenari comuni che richiedono opzioni di configurazione avanzate

Il nome della proprietà viene riutilizzato con valori diversi

In alcune API, lo stesso nome di proprietà o parametro può essere riutilizzato in metodi diversi, ma con valori differenti. Ad esempio, un'API potrebbe specificare che il parametro name per la creazione di una risorsa (una richiesta POST) potrebbe avere il valore foo/bar, mentre lo stesso campo name per le richieste di aggiornamento (PATCH o PUT) potrebbe richiedere il valore foo/bar/baz.

I valori delle proprietà possono essere dedotti dalla risposta dell'API

Alcuni metodi dell'API richiedono un valore generato dal server che viene restituito effettui una richiesta GET alla risorsa. Ad esempio, un'API potrebbe richiedere un parametro etag per effettuare richieste di aggiornamento quando si muta una risorsa. etag cambia dopo ogni richiesta di modifica, in modo da ottenere il valore etag eseguendo una richiesta GET alla risorsa, prima di effettuare la richiesta di aggiornamento della risorsa.

Utilizzando le mappature di input, puoi indicare a Deployment Manager che il campo etag può essere recuperato dalla risorsa dell'API. Deployment Manager esegue automaticamente una richiesta GET per ottenere questo valore quando un utente chiama il metodo specificato nelle mappature di input.

Semplifica l'input utente

Deployment Manager supporta le proprietà virtuali, ovvero proprietà arbitrarie che puoi esporre agli utenti tramite Deployment Manager per usi diversi. Tratta le proprietà virtuali come se non esistessero nell'API sottostante, ma come variabili arbitrarie di cui puoi iniettare il valore, se necessario, nelle mappature di input. Ad esempio, immagina che esista una proprietà dell'API che deve essere codificata in base64 prima che il valore venga inviato all'API sottostante. Invece di chiedere ai tuoi agli utenti di fornire il valore della codifica Base64, puoi creare un'istanza che richiede agli utenti il valore di testo normale, quindi codifica in Base64 con le mappature di input e, infine, fornire il risultato all'API sottostante.

Specificare le opzioni avanzate

Per specificare le opzioni avanzate, fornisci la proprietà collectionOverrides quando creando la risorsa del provider dei tipi e definire le mappature di input proprietà di ciascuna raccolta di API.

Ad esempio, con gcloud CLI, puoi fornire opzioni avanzate utilizzando una YAML e fornisci il file YAML con la tua richiesta type-providers create. Un file YAML di esempio potrebbe avere il seguente aspetto:

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]

Questa configurazione indica a Deployment Manager:

  • Per il metodo create, cerca il campo denominato emailAddress.displayName nel corpo della risorsa e impostare il valore di quel campo sull'input dell'utente per displayName nella configurazione di Deployment Manager. Pertanto, se un utente imposta la configurazione nel seguente modo:

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

    Deployment Manager imposterà il valore di emailAddress.displayName su John Doe.

  • Per il metodo update, il campo si trova nel percorso della risorsa anziché nel corpo della risorsa, ma viene applicata la stessa mappatura di input.

Specificare le mappature di input

Una mappatura di input consente di mappare o iniettare informazioni per determinati campi dell'API in modo che Deployment Manager possa interagire più facilmente con l'API sottostante, sollevando gli utenti dall'oneroso compito di comprendere il comportamento sottile dell'API.

Utilizza le mappature di input per semplificare il modo in cui gli utenti interagiscono con l'API. Ad esempio, puoi utilizzare le mappature di input per ottenere automaticamente i valori generati dal server, come impronte, ID o etag. In questo modo gli utenti non devono più preoccuparsi eseguendo una richiesta get separata sulla risorsa ogni volta che vuole effettuare un aggiornamento.

Analogamente, puoi utilizzare le mappature di input anche per gestire situazioni ambigue o confuse in cui lo stesso campo dell'API ha valori diversi per metodi diversi. Ad esempio, una richiesta di creazione di una risorsa potrebbe richiedere una proprietà name che l'utente può specificare, ma la stessa API potrebbe richiedere una proprietà name in un formato diverso per i metodi update. Puoi utilizzare le mappature di input per indicare a Deployment Manager il valore appropriato per ogni metodo dell'API.

Per specificare le mappature di input per un provider dei tipi, fornisci il parametro options.inputMappings proprietà. Puoi definire le mappature di input che si applicano l'intera API oppure puoi fornire esplicitamente le mappature di input per ogni raccolta:

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

Di seguito sono descritte le parti importanti di questa sintassi.

Raccolta

[SPECIFIC_COLLECTION] è la raccolta API per cui questa mappatura di input . Ad esempio, se fornisci mappature di input per un documento Google Discovery, come l'API Account di servizio IAM, le raccolte pertinenti sono projects.serviceAccounts e projects.serviceAccountKeys.

Per un'API che utilizza la specifica OpenAPI, il percorso della raccolta potrebbe essere /example-collection/{name}. Puoi esplorare una funzionalità Esempio di OpenAPI nella Repository GitHub OpenAPI.

Nome campo

"fieldName" è l'attributo o la proprietà dell'API per la quale vuoi specificare la mappatura dell'input. Ad esempio, "fieldName": "fingerprint", "fieldName": "etag" e così via.

Località

Le proprietà dell'API possono apparire come parametri nel percorso dell'URL o come parte di il corpo della richiesta o della risposta. Specifica dove si applica questa mappatura di input, ad esempio l'URL PATH o la richiesta BODY come posizione. I valori supportati sono:

  • PATH
  • BODY
  • QUERY
  • HEADER

Corrispondenza metodo

Specifica a quali metodi si applica questa mappatura di input. Utilizza le espressioni regolari per specificare più metodi. Ad esempio:

"methodMatch":"^create$"

Per le specifiche OpenAPI, puoi:

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

Valore

Specifica il valore che Deployment Manager deve inserire per questo campo. Questo campo utilizza la notazione JSONPath. Ad esempio, questa mappatura di input indica che per il campo name, Deployment Manager deve prendere il valore fornito dall'utente e inserirlo nel formato projects/$.project/topics/$resource.properties.topic:

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

  • Quando utilizzi $.resource.properties.[VARIABLE], imposti il valore di una proprietà che l'utente imposterà nella sua configurazione. Ad esempio, per $.resource.properties.topic, il valore sarà il valore fornito dall'utente per la proprietà topic nella relativa configurazione:

    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

  • Per fare riferimento alla risorsa stessa dopo una richiesta get, utilizza $.resource.self.[VARIABLE]. Ad esempio, per le richieste di aggiornamento, se vuoi recuperare l'impronta più recente, puoi utilizzare questa sintassi per indicare a Deployment Manager di eseguire un get e acquisire il valore:

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

Utilizzo di proprietà virtuali

Le proprietà virtuali sono proprietà arbitrarie che puoi esporre agli utenti tramite Deployment Manager. Queste proprietà non fanno parte dell'API sottostante, ma sono variabili arbitrarie che possono essere utilizzate per trasmettere informazioni o nascondere incoerenze dell'API agli utenti. Puoi fare riferimento nelle mappature di input.

Le proprietà virtuali seguono lo schema JSON 4. Fornisci proprietà virtuali come parte di options per una raccolta specifica:

"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 un file di definizione YAML, il codice sarà simile al seguente:

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

Considera ad esempio un'API falsa che genera indirizzi email. Supponiamo che l'API abbia un metodo per creare un'email che accetti una proprietà emailAddress.displayName. Quando un utente richiede di creare un indirizzo email, fornisce un come in questo caso:

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

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

Supponiamo ora che l'API mostri un modo per aggiornare l'indirizzo email, ma il metodo per aggiornare un'email richiede solo la proprietà displayName, anziché la Proprietà email.displayName:

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

{
  "displayName": "josh"
}

In che modo ti aspetti che gli utenti forniscano questo valore quando utilizzano questo tipo? fornitore? Potresti chiedere di specificare la proprietà in modo diverso a seconda dell'operazione:

# 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

In alternativa, puoi creare una proprietà virtuale che abbia lo stesso valore, a prescindere dall'operazione, quindi ricorri alle mappature di input per mappare il al parametro API appropriato. Per questo esempio, supponiamo che tu abbia definito una proprietà virtuale denominata displayName. Le mappature di input potrebbero quindi avere il seguente aspetto:

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

Nello specifico, la proprietà virtuale è definita qui:

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

In formato leggibile:

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

Ora gli utenti possono specificare displayName come proprietà di primo livello sia per le richieste di aggiornamento che per quelle di creazione e Deployment Manager saprà come mappare correttamente il valore.

# 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

Passaggi successivi