Aggiunta di un'API come provider di tipi

Questa pagina descrive come aggiungere un'API a Google Cloud Deployment Manager come provider di tipi. Per scoprire di più sui tipi e sui provider di tipi, consulta la documentazione Panoramica dei tipi.

Un provider di tipi espone tutte le risorse di un'API di terze parti a Deployment Manager come tipi di base che puoi utilizzare nelle configurazioni. Questi tipi devono essere forniti direttamente da un'API RESTful che supporta le operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD).

Se vuoi utilizzare un'API non fornita automaticamente da Google con Deployment Manager, devi aggiungerla come provider di tipi. Puoi aggiungere qualsiasi API come provider di tipi, a condizione che l'API abbia una specifica OpenAPI (in precedenza Swagger©) o un documento di rilevamento Google.

Questo documento non descrive come configurare il tuo servizio API. Si presuppone che esista già un'API che vuoi aggiungere o che tu abbia già creato un'API in esecuzione accessibile da un endpoint pubblico. Ad esempio, per eseguire il deployment di un'API di esempio utilizzando Google Cloud Endpoints, puoi seguire la guida rapida di Cloud Endpoints.

Prima di iniziare

  • Se vuoi utilizzare gli esempi di riga di comando in questa guida, installa lo strumento a riga di comando `gcloud`.
  • Se vuoi utilizzare gli esempi di API in questa guida, configura l'accesso API.
  • Configura l'accesso all'API v2beta se vuoi utilizzare gli esempi di API in questa guida.

Componenti di un provider di tipi

Un provider di tipi è costituito da:

  • Nome: il nome desiderato del provider di tipi. Utilizzerai questo nome per fare riferimento al tipo e alle relative risorse API.
  • Documento descrittore: l'URL del documento descrittore per il tipo. I documenti supportati includono documenti di rilevamento Google o specifiche OpenAPI 1.2.
  • Autenticazione:tutte le credenziali di autenticazione necessarie per l'API. Puoi specificare l'autenticazione di base. Se la tua API è in esecuzione su Cloud Endpoints o Google Kubernetes Engine (GKE), puoi utilizzare anche le credenziali del account di servizio del progetto come autenticazione.
  • Opzioni avanzate: tutti i mapping di input avanzati o le opzioni API.

Nome

Il nome del provider di tipi. Utilizzerai questo nome per fare riferimento al tipo nelle configurazioni e nei modelli futuri. Ad esempio, se hai creato un provider di tipi e l'hai chiamato my-awesome-type-provider, lo utilizzerai nei modelli successivi nel seguente modo:

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

dove my-project è l'ID progetto a cui appartiene il tipo e some-collection è il percorso della risorsa API che stai creando.

Documento descrittore

Il documento descrittore per un provider di tipi può essere una specifica OpenAPI 1.2 o 2.0 oppure un documento di rilevamento Google. Ad esempio, puoi trovare il documento di rilevamento Google per l'API Compute Engine Beta a questo URL:

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

Consulta l'elenco completo dei documenti di rilevamento Google.

Sono accettabili anche i documenti OpenAPI 1.2 e OpenAPI 2.0.

Autenticazione

Se la tua API richiede l'autenticazione, puoi fornire i dettagli di autenticazione qui. Deployment Manager supporta le credenziali di autenticazione di base, come nome utente e password. Per Google Kubernetes Engine e Google Cloud Endpoints, puoi utilizzare l'intestazione Authorization per fornire un token di accesso dal account di servizio del progetto.

Per specificare le credenziali di autenticazione di base, fornisci il nome utente e la password nella sezione credentials:

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Devi specificare il nome utente e la password solo la prima volta che crei un provider di tipi.

Se hai un cluster in esecuzione su Google Kubernetes Engine (GKE) nello stesso progetto in cui utilizzi Deployment Manager, puoi aggiungere il cluster come provider di tipi e utilizzare Deployment Manager per accedere all'API GKE. In questo scenario, puoi ottenere il token di accesso OAuth 2.0 del service account delle API Google del progetto e fornire il token di accesso nell'intestazione Authorization. A differenza della sezione delle credenziali precedente, devi fornire questo valore come mapping di input nella richiesta:

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

Il metodo googleOauth2AccessToken() recupererà automaticamente un token di accesso quando l'utente chiama questo provider di tipi. Per un esempio completo, consulta l' esempio di cluster e tipo GKE.

Puoi utilizzare lo stesso metodo per autenticarti in Google Cloud Endpoints.

(Facoltativo) Root dell'autorità di certificazione personalizzata

Se vuoi aggiungere un'API come provider di tipi a Deployment Manager e l'endpoint HTTPS dell'API utilizza un certificato non fornito da un'autorità di certificazione (CA) pubblicamente attendibile per criptare la connessione, puoi aggiungere l'API alla configurazione come nell'esempio seguente:

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

dove my-gke-cluster è il cluster GKE che stai utilizzando. Per un esempio dettagliato, consulta l' esempio di cluster del provider GKE.

Opzioni avanzate per i tipi

Alcune API potrebbero avere caratteristiche che rendono difficile per Deployment Manager mappare tutte le proprietà dell'API a Deployment Manager. In uno scenario ideale, fornisci un documento descrittore e Deployment Manager individua automaticamente i percorsi delle richieste API e le proprietà API pertinenti senza ulteriori interventi da parte tua. Per le API più complesse, Deployment Manager può comprendere la maggior parte dell'API, ma potrebbe essere necessario specificare esplicitamente i mapping di input per il comportamento dell'API che non è ovvio.

Per scoprire di più sui mapping di input, consulta la documentazione relativa alle opzioni API avanzate.

Creazione di un provider di tipi

Per creare un provider di tipi, invia una richiesta a Deployment Manager con un payload di richiesta contenente il nome del provider di tipi desiderato, l'URL del descrittore e le credenziali di autenticazione necessarie.

gcloud

Per creare un provider di tipi utilizzando gcloud CLI, utilizza il comando type-providers create:

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

dove:

  • [TYPE_PROVIDER_NAME] è il nome che vuoi assegnare a questo tipo.

  • [URL] è l'URL completo del documento descrittore che supporta questo tipo. Ad esempio:

    http://petstore.swagger.io/v2/swagger.json

Se vuoi fornire credenziali di autenticazione o opzioni API avanzate, puoi creare un file di opzioni API scritto in YAML e fornirlo utilizzando il --api-options-file flag. Ad esempio, il file 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
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Il comando gcloud sarà:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

Se vuoi autenticarti utilizzando un'autorità di certificazione (CA) personalizzata, puoi aggiungere la CA come flag al comando gcloud, come nell'esempio seguente:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

API

Per creare un tipo di base nell'API, invia una POST richiesta che contenga descriptorUrl e opzioni di configurazione facoltative nel corpo della richiesta. Ad esempio:

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "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"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

Per ulteriori informazioni, consulta la documentazione relativa al insert metodo.

Test del provider di tipi

Per verificare che il tipo di provider di tipi funzioni come previsto:

  1. Chiama il nuovo provider di tipi in una configurazione.
  2. Esegui il deployment di ogni raccolta fornita dal provider di tipi per assicurarti che l'API funzioni come previsto. Una raccolta è una risorsa API del provider di tipi specificato.
  3. Apporta un aggiornamento a ogni raccolta.
  4. Elimina ogni raccolta.

Quando un utente crea un'istanza di un tipo dal tuo provider di tipi, in realtà sta inviando una richiesta a Deployment Manager, non esplicitamente all'API sottostante. A sua volta, Deployment Manager crea la richiesta con le informazioni fornite per inviare una richiesta all'API per conto dell'utente. Il problema più comune che potresti riscontrare è che l'API ha proprietà che Deployment Manager non riesce a riconoscere automaticamente. Ad esempio, alcune API richiedono proprietà che possono essere estratte solo da una risposta API. Altre API potrebbero utilizzare lo stesso nome di campo con valori diversi a seconda dell'operazione. In questi casi, dovrai indicare esplicitamente a Deployment Manager come gestire questi scenari.

Se la tua API presenta una di queste caratteristiche, utilizza i mapping di input per chiarire l'ambiguità per Deployment Manager.

Passaggi successivi

© 2016 Swagger. Tutti i diritti riservati.