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 relativa alla 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 tue configurazioni. Questi tipi devono essere pubblicati direttamente da un'API RESTful che supporta le operazioni Create, Read, Update and Delete (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 disponga di una specifica OpenAPI (in precedenza Swagger^©) o di un documento Google Discovery.

Questo documento non descrive come implementare il tuo servizio API. Si assume che esista già un'API che vuoi aggiungere o che hai 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 introduttiva 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. Utilizzalo per fare riferimento al tipo e alle relative risorse API pertinenti.
• Documento descrittivo: l'URL del documento descrittivo per il tipo. I documenti supportati includono i documenti Google Discovery o le specifiche OpenAPI 1.2.
• Autenticazione:eventuali 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 dell'account di servizio del progetto per l'autenticazione.
• Opzioni avanzate: eventuali mappature di input avanzate o opzioni API.

Nome

Il nome del provider di tipi. Utilizzerai questo nome per fare riferimento al tipo in configurazioni e modelli futuri. Ad esempio, se hai creato un provider di tipi e lo hai denominato my-awesome-type-provider, lo utilizzerai nei modelli successivi come segue:

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 descrittivo

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

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

Consulta l'elenco completo dei documenti di Google Discovery.

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 gli endpoint Google Kubernetes Engine e Google Cloud, puoi utilizzare l'intestazione Authorization per fornire un token di accesso dall'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 fornitore di tipi.

Se hai un cluster in esecuzione su Google Kubernetes Engine (GKE) nello stesso progetto in cui utilizzi Deployment Manager, puoi aggiungerlo 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 dell'account di servizio API di Google del progetto e fornirlo nell'intestazione Authorization. A differenza della sezione precedente relativa alle credenziali, devi fornire questo valore come mappatura di input nella richiesta:

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

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

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

(Facoltativo) Autorità di certificazione radice 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 in uso. Per un esempio dettagliato, consulta il cluster di provider GKE di esempio.

Opzioni di tipo avanzate

Alcune API potrebbero avere idiosincrasie 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 dell'API e le proprietà dell'API pertinenti senza ulteriore intervento da parte tua. Per le API più complesse, Deployment Manager può comprendere la maggior parte dell'API, ma potrebbe essere necessario specificare esplicitamente le mappature di input per il comportamento dell'API non ovvio.

Per scoprire di più sulle mappature degli input, leggi la documentazione relativa alle opzioni avanzate per le API.

Creazione di un provider di tipi

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

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

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]

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

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

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

Test del provider di tipi

Per verificare che il tipo di fornitore 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. Esegui un aggiornamento di ogni collezione.
4. Elimina ogni raccolta.

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

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

Passaggi successivi

• Scopri come chiamare un provider di tipi.
• Condividi il provider di tipi con altri progetti.
• Scopri di più sui tipi.
• Scopri di più sulla creazione di una configurazione.
• Crea un deployment.
• Scopri di più sulle opzioni API avanzate.

^{© 2016 Swagger. Tutti i diritti riservati.}