Adicionar uma API como fornecedor de tipos

Esta página descreve como adicionar uma API ao Google Cloud Deployment Manager como um fornecedor de tipos. Para saber mais sobre os tipos e os fornecedores de tipos, leia a documentação de vista geral dos tipos.

Um fornecedor de tipos expõe todos os recursos de uma API de terceiros ao Deployment Manager como tipos base que pode usar nas suas configurações. Estes tipos têm de ser fornecidos diretamente por uma API RESTful que suporte as operações de criação, leitura, atualização e eliminação (CRUD).

Se quiser usar uma API que não seja fornecida automaticamente pela Google com o Deployment Manager, tem de adicionar a API como um fornecedor de tipos. Pode adicionar qualquer API como fornecedor de tipos, desde que essa API tenha uma especificação OpenAPI (anteriormente Swagger©) ou um documento Google Discovery.

Este documento não descreve como configurar o seu próprio serviço de API. A suposição é que já existe uma API que quer adicionar ou que já criou uma API em execução acessível a partir de um ponto final público. Por exemplo, para implementar uma API de exemplo através do Google Cloud Endpoints, pode seguir o guia de início rápido do Cloud Endpoints.

Antes de começar

Componentes de um fornecedor de tipos

Um fornecedor de tipos é composto por:

  • Nome: o nome pretendido do fornecedor de tipos. Vai usar este nome para fazer referência ao tipo e aos respetivos recursos da API.
  • Documento descritor: o URL do documento descritor para o tipo. Os documentos suportados incluem documentos Google Discovery ou especificações OpenAPI 1.2.
  • Autenticação: quaisquer credenciais de autenticação necessárias para a API. Pode especificar autenticação básica. Se a sua API estiver a ser executada no Cloud Endpoints ou no Google Kubernetes Engine (GKE), também pode usar as credenciais da conta de serviço do projeto como autenticação.
  • Opções avançadas: quaisquer mapeamentos de entrada avançados ou opções de API.

Nome

O nome do fornecedor de tipos. Vai usar este nome para se referir ao tipo em configurações e modelos futuros. Por exemplo, se criou um fornecedor de tipos e lhe deu o nome my-awesome-type-provider, usá-lo-ia em modelos subsequentes da seguinte forma:

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

onde my-project é o ID do projeto ao qual o tipo pertence e some-collection é o caminho para o recurso da API que está a criar.

Documento descritor

O documento descritor de um fornecedor de tipos pode ser uma especificação OpenAPI 1.2 ou 2.0, ou um documento Google Discovery. Por exemplo, pode encontrar o documento de descoberta da API Compute Engine Beta neste URL:

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

Consulte uma lista completa de documentos do Google Discovery.

Os documentos OpenAPI 1.2 e OpenAPI 2.0 também são aceitáveis.

Autenticação

Se a sua API requer autenticação, pode fornecer os detalhes de autenticação aqui. O Deployment Manager suporta credenciais de autenticação básica, como um nome de utilizador e uma palavra-passe. Para o Google Kubernetes Engine e os Google Cloud Endpoints, pode usar o cabeçalho Authorization para fornecer um token de acesso da conta de serviço do projeto.

Para especificar credenciais de autenticação básica, indique o nome de utilizador e a palavra-passe na secção credentials:

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

Só tem de especificar o nome de utilizador e a palavra-passe na primeira vez que criar um fornecedor de tipos.

Se tiver um cluster em execução no Google Kubernetes Engine (GKE) no mesmo projeto em que está a usar o Deployment Manager, pode adicionar o cluster como um fornecedor de tipos e usar o Deployment Manager para aceder à API GKE. Neste cenário, pode obter o token de acesso do OAuth 2.0 da conta de serviço das APIs Google do projeto e fornecer o token de acesso no cabeçalho Authorization. Ao contrário da secção de credenciais anterior, tem de fornecer isto como um mapeamento de entrada no seu pedido:

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

O método googleOauth2AccessToken() recebe automaticamente um token de acesso quando o utilizador chama este fornecedor de tipos. Para ver um exemplo completo, consulte o exemplo de tipo e cluster do GKE.

Pode usar o mesmo método para autenticar os Google Cloud Endpoints.

(Opcional) Raiz da autoridade de certificação personalizada

Se quiser adicionar uma API como fornecedor de tipos ao Deployment Manager e o ponto final HTTPS dessa API usar um certificado que não seja fornecido por uma autoridade de certificação (AC) fidedigna publicamente para encriptar a ligação, pode adicionar a API à sua configuração, como no exemplo seguinte:

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

em que my-gke-cluster é o cluster do GKE que está a usar. Para ver um exemplo detalhado, consulte o exemplo de cluster do fornecedor do GKE.

Opções de tipo avançadas

Determinadas APIs podem ter idiossincrasias que dificultam o mapeamento de todas as propriedades da API para o Deployment Manager. Num cenário ideal, fornece um documento descritor e o Deployment Manager determina automaticamente os caminhos de pedidos de API e as propriedades de API relevantes sem trabalho adicional da sua parte. Para APIs mais complexas, o Deployment Manager pode compreender a maioria da API, mas pode ter de especificar explicitamente mapeamentos de entrada para o comportamento da API que não seja óbvio.

Para saber mais acerca dos mapeamentos de entrada, leia a documentação sobre as opções avançadas da API.

Criar um fornecedor de tipos

Para criar um fornecedor de tipos, faça um pedido ao Deployment Manager com um payload de pedido que contenha o nome do fornecedor de tipos pretendido, o URL do descritor e as credenciais de autenticação necessárias.

gcloud

Para criar um fornecedor de tipos através da CLI gcloud, use o comando type-providers create:

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

where:

  • [TYPE_PROVIDER_NAME] é o nome que quer dar a este tipo.

  • [URL] é o URL totalmente qualificado para o documento descritor que suporta este tipo. Por exemplo:

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

Se quiser fornecer credenciais de autenticação ou opções avançadas da API, pode criar um ficheiro de opções da API escrito em YAML e fornecê-lo através da flag --api-options-file. Por exemplo, o ficheiro pode ter este aspeto:

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]

O comando gcloud seria:

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

Se quiser autenticar através de uma autoridade de certificação (CA) personalizada, pode adicionar a CA como uma flag ao comando gcloud, como no seguinte exemplo:

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

API

Para criar um tipo base na API, faça um pedido POST que contenha o descriptorUrl e opções de configuração opcionais no corpo do pedido. Por exemplo:

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

Para mais informações, consulte a documentação do método insert.

Testar o seu fornecedor de tipos

Para verificar se o seu tipo de fornecedor de tipos funciona como esperado:

  1. Chame o seu novo fornecedor de tipos numa configuração.
  2. Implemente cada recolha fornecida pelo fornecedor de tipos para garantir que a API funciona como esperado. Uma coleção é um recurso de API do fornecedor de tipos especificado.
  3. Faça uma atualização a cada coleção.
  4. Elimine cada coleção.

Quando um utilizador instancia um tipo do seu fornecedor de tipos, está a fazer um pedido ao Deployment Manager e não explicitamente à API subjacente. Por sua vez, o Deployment Manager cria o pedido com as informações fornecidas para fazer um pedido à API em nome do utilizador. O problema mais comum que pode encontrar é que a API tem propriedades difíceis de reconhecer automaticamente para o Deployment Manager. Por exemplo, algumas APIs requerem propriedades que só podem ser extraídas de uma resposta da API. Outras APIs podem usar o mesmo nome do campo com valores diferentes consoante a operação. Nestes casos, tem de indicar explicitamente ao Deployment Manager como processar estes cenários.

Se a sua API tiver alguma destas caraterísticas, use mapeamentos de entrada para esclarecer a ambiguidade para o Deployment Manager.

O que se segue?

© 2016 Swagger. Todos os direitos reservados.