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 saperne di più sui tipi e sui provider di tipi, consulta la documentazione della 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 forniti direttamente da un'API RESTful che supporta CRUD (Create, Read, Update ed Delete).

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

Questo documento non descrive come creare un servizio API personalizzato. Supponiamo che tu voglia aggiungere già un'API 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 a riga di comando di questa guida, installa lo strumento a riga di comando "gcloud".
Se vuoi utilizzare gli esempi di API descritti in questa guida, configura l'accesso alle API.
Configura l'accesso all'API v2beta se vuoi utilizzare gli esempi di API descritti in questa guida.

Componenti di un provider di tipo

Un provider di tipi è composto da:

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

Nome

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

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, il documento di Google Discovery relativo all'API Compute Engine beta è disponibile a questo URL:

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

Consulta un 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 di autenticazione qui. Deployment Manager supporta le credenziali di autenticazione di base, come nome utente e password. Per Google Kubernetes Engine e gli endpoint 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 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 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 precedente, devi specificare quanto segue come mappatura degli 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 provider di tipo. Per un esempio completo, vedi l'esempio di cluster e tipo di GKE.

Puoi utilizzare lo stesso metodo per l'autenticazione agli endpoint Google Cloud.

(Facoltativo) Autorità di certificazione personalizzata radice

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 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, fai riferimento all'esempio di cluster del provider GKE.

Opzioni di tipo avanzate

Alcune API potrebbero avere delle 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 determina automaticamente i percorsi delle richieste API e le proprietà API pertinenti senza alcun intervento aggiuntivo da parte tua. Per API più complesse, Deployment Manager è in grado di comprendere la maggior parte delle API, ma potrebbe essere necessario specificare esplicitamente le mappature di input a un comportamento dell'API non ovvio.

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

Creazione di un provider di tipi

Per creare un provider di tipi, effettua una richiesta a Deployment Manager con un payload di richiesta contenente il nome del provider del tipo desiderato, l'URL descrittore ed eventuali 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 delle opzioni API scritto in YAML e fornirlo utilizzando il flag --api-options-file. 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 sarebbe:

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

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

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, effettua una richiesta POST che contenga descriptorUrl e una 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 metodo insert.

Test del provider di tipi in corso...

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

Chiama il nuovo fornitore di tipi in una configurazione.
Esegui il deployment di ogni raccolta fornita dal provider del tipo per garantire che l'API funzioni come previsto. Una raccolta è una risorsa API del provider del tipo specificato.
Aggiorna ogni collezione.
Elimina ogni raccolta.

Quando un utente crea un'istanza di un tipo dal tuo provider 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 dispone di proprietà difficili da riconoscere automaticamente da Deployment Manager. 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, devi indicare esplicitamente a Deployment Manager come gestire questi scenari.

Se la tua API ha uno di questi trait, utilizza le mappature di input per chiarire l'ambiguità per Deployment Manager.

Passaggi successivi

Scopri come chiamare un fornitore di tipi.
Condividi il tuo fornitore di tipi con altri progetti.
Scopri di più sui tipi.
Scopri come creare una configurazione.
Crea un deployment.
Scopri di più sulle opzioni avanzate dell'API.