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 supporti le operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD).

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

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 fornitore 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 i documenti Google Discovery o le specifiche OpenAPI 1.2.
• Autenticazione: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: eventuali mappature di input avanzate o opzioni API.

Nome

Il nome del fornitore del tipo. 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 utilizzeresti 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 Google Discovery. 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 Google Discovery.

Sono accettati anche i documenti OpenAPI 1.2 e OpenAPI 2.0.

Autenticazione

Se la tua API richiede l'autenticazione, puoi fornire i dettagli 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 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 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 fornitore 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 delle API di Google del progetto e fornire il token di accesso nell'intestazione Authorization. A differenza della sezione delle credenziali precedenti, devi fornire questo valore come mappatura dell'input nella tua richiesta:

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

Il metodo googleOauth2AccessToken() recupererà 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 l'autenticazione in Google Cloud Endpoints.

(Facoltativo) Radice 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) attendibile pubblicamente per criptare la connessione, puoi aggiungere l'API alla tua 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 particolari che rendono difficile per Deployment Manager mappare tutte le proprietà dell'API in 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 potresti dover specificare esplicitamente i mapping di input al comportamento dell'API che non è ovvio.

Per saperne di più sui mapping degli input, leggi la documentazione relativa alle opzioni avanzate dell'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 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 fornitore di tipi

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

Quando un utente crea un'istanza di un tipo dal tuo fornitore di tipi, in realtà sta effettuando 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 API. Altre API potrebbero utilizzare lo stesso nome del campo con valori diversi a seconda dell'operazione. In questi casi, devi 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

• Scopri come chiamare un fornitore di servizi di composizione.
• Condividere il provider di tipi con altri progetti.
• Scopri di più sui tipi.
• Scopri di più sulla creazione di una configurazione.
• Creare un deployment.
• Scopri di più sulle opzioni avanzate dell'API.

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