Questa pagina è stata tradotta dall'API Cloud Translation.

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 ulteriori informazioni su tipi e provider di tipi, consulta le documentazione della panoramica sui tipi.

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

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, a condizione che disponga di una specifica OpenAPI (in precedenza Swagger^©) o di un documento Google Discovery.

Questo documento non descrive come supportare 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 le 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 tipo

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 quelli di Google Discovery o OpenAPI 1.2 specifiche.
Autenticazione: eventuali credenziali di autenticazione necessarie per l'API. Puoi specificare autenticazione di base. Se l'API è in esecuzione su Cloud Endpoints o Google Kubernetes Engine (GKE), puoi anche utilizzare le credenziali dell'account di servizio progetto come 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 dei tipi con il nome my-awesome-type-provider, lo useresti nelle modelli simili:

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 dei tipi può essere un OpenAPI 1.2 o 2.0 o un documento di Google Discovery. Ad esempio, puoi trovare Documento di rilevamento di Google per l'API Compute Engine beta a questo URL:

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

Consulta un elenco completo dei documenti di Google Discovery.

Sono accettabili anche i documenti OpenAPI 1.2 e OpenAPI 2.0.

Autenticazione

Se l'API richiede l'autenticazione, puoi fornire l'autenticazione i dettagli qui. Deployment Manager supporta le credenziali di autenticazione di base, come un nome utente e una password. Per Google Kubernetes Engine e Google Cloud Endpoint, puoi utilizzare l'intestazione Authorization per fornire un di accesso a un token di accesso all'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 di nella sezione delle credenziali precedente, devi fornirla 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 l'autenticazione in Google Cloud Endpoint.

(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 che non è fornito da un l'autorità di certificazione (CA) 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, consulta il cluster del provider GKE di esempio.

Opzioni di tipo avanzate

Alcune API potrebbero avere idiosincrasie che rendono difficile Deployment Manager per mappare tutte le proprietà dell'API a con 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 maggiori informazioni a quelle complesse, Deployment Manager è in grado di comprendere la maggior parte delle API, potresti dover specificare esplicitamente le mappature di input al comportamento dell'API che non ovvio.

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

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

Per creare un provider di tipi utilizzando gcloud CLI, utilizza 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 a supporto di questo tipo. Ad esempio:
```
http://petstore.swagger.io/v2/swagger.json
```

Se vuoi fornire le credenziali di autenticazione o le opzioni API avanzate, puoi creare un file di 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 sarà:

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

Test del provider del tipo

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

Chiama il nuovo fornitore di tipi in una configurazione.
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 del tipo specificato.
Esegui un aggiornamento di ogni collezione.
Elimina ogni raccolta.

Quando un utente crea un'istanza di un tipo dal tuo provider del tipo, in realtà sta creando 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à 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, devi indicare esplicitamente a Deployment Manager come gestire diversi 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 fornitore di servizi di tipo.
Condividi il tuo provider del tipo 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.