Como adicionar uma API como um provedor de tipos

Nesta página, descrevemos como adicionar uma API ao Google Cloud Deployment Manager como um provedor de tipos. Para saber mais sobre tipos e provedores de tipos, leia a documentação sobre Visão geral de tipos.

O provedor de tipos expõe todos os recursos de uma API de terceiros ao Deployment Manager como tipos básicos que podem ser usados nas configurações. Esses tipos precisam ser exibidos diretamente por uma API RESTful com suporte para criar, ler, atualizar e excluir (CRUD, na sigla em inglês).

Se você quiser usar uma API que não é fornecida automaticamente pelo Google com o Deployment Manager, adicione a API como um provedor de tipos. É possível adicionar qualquer API como um provedor de tipos, desde que ela tenha uma especificação OpenAPI (antes conhecida como Swagger^©) ou um documento do Google Discovery.

Este documento não descreve como manter seu próprio serviço de API. Partimos do pressuposto que já existe uma API a ser adicionada ou que você já criou uma API que está em execução e é acessível a partir de um ponto de extremidade público. Por exemplo, para implantar uma API de amostra usando o Google Cloud Endpoints, siga o Guia de início rápido do Cloud Endpoints.

Antes de começar

Para usar os exemplos de linha de comando deste guia, instale a ferramenta de linha de comando "gcloud".
Para usar os exemplos de API deste guia, configure o acesso de API.
Configure o acesso à API v2beta para usar os exemplos de API deste guia.

Componentes do provedor de tipos

Um provedor de tipos consiste em:

Nome: o nome desejado do provedor de tipos. Você usará esse nome para fazer referência ao tipo e aos respectivos recursos relevantes de API.
Documento descritor: o URL do documento descritor do tipo. Os documentos compatíveis incluem os documentos Google Discovery e as especificações OpenAPI 1.2.
Autenticação: todas as credenciais de autenticação necessárias para a API. É possível especificar a autenticação básica. Se a API estiver sendo executada no Cloud Endpoints ou no Google Kubernetes Engine (GKE), também é possível usar as credenciais da conta de serviço do projeto como autenticação.
Opções avançadas: todos os mapeamentos de entrada ou opções avançadas da API.

Nome

O nome do provedor de tipos. Você usará esse nome para fazer referência ao tipo em configurações e modelos futuros. Por exemplo, se você tiver criado um provedor de tipos chamado my-awesome-type-provider, ele será usado nos modelos seguintes, como:

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

Em que my-project é o ID do projeto ao que o tipo pertence e some-collection é o caminho para o recurso de API que você está criando.

Documento descritor

O documento descritor de um provedor de tipos pode ser um documento do Google Discovery ou uma especificação OpenAPI 1.2 ou 2.0. Por exemplo, você pode encontrar o documento Google Discovery para a Compute Engine Beta API neste URL:

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

Veja a lista completa dos documentos Google Discovery.

Os documentos OpenAPI 1.2 e OpenAPI 2.0 também são aceitos.

Authentication

Se a API requer autenticação, é possível fornecer os detalhes de autenticação aqui. O Deployment Manager é compatível com credenciais de autenticação básicas, como nome de usuário e senha. Para o Google Kubernetes Engine e o Google Cloud Endpoints, use o cabeçalho Authorization para fornecer um token de acesso da conta de serviço do projeto.

Para especificar credenciais de autenticação básicas, forneça o nome de usuário e a senha na seção credentials:

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

Basta especificar o nome de usuário e a senha na primeira vez que você criar um provedor de tipos.

Se você tiver um cluster em execução no Google Kubernetes Engine (GKE) no mesmo projeto em que está usando o Deployment Manager, poderá adicionar esse cluster como um provedor de tipos e usar o Deployment Manager para acessar a API GKE. Nesse cenário, é possível conseguir o token de acesso OAuth 2.0 da conta de serviço de APIs do Google do projeto e fornecê-lo no cabeçalho de Authorization. Diferentemente da seção de credenciais anterior, é necessário fornecer isso como um mapeamento de entrada na solicitação:

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

O método googleOauth2AccessToken() receberá automaticamente um token de acesso quando o usuário chamar esse provedor de tipos. Para ver um exemplo completo, consulte a amostra de tipo e cluster do GKE.

Você pode usar o mesmo método para fazer a autenticação no Google Cloud Endpoints.

(Opcional) raiz de autoridade de certificação personalizada

Se você quiser adicionar uma API como um provedor de tipos ao Deployment Manager e o endpoint HTTPS dessa API usar um certificado que não é fornecido por uma autoridade de certificação (CA, na sigla em inglês) publicamente confiável para criptografar a conexão, adicione a API à configuração como no exemplo a seguir:

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

em que my-gke-cluster é o cluster do GKE que você está usando. Para ver um exemplo detalhado, consulte a amostra de cluster de provedor do GKE.

Opções de tipo avançadas

Algumas APIs podem conter especificidades que dificultam o mapeamento de todas as propriedades da API pelo Deployment Manager. Idealmente, você fornece um documento de descritor e o Deployment Manager descobre automaticamente os caminhos das solicitações e as propriedades relevantes da API, sem qualquer trabalho adicional da sua parte. No caso das APIs mais complexas, o Deployment Manager consegue entender a maior parte da API. No entanto, talvez seja necessário especificar explicitamente os mapeamentos de entrada para os comportamentos da API que não sejam óbvios.

Para saber mais sobre mapeamentos de entrada, leia o documento Opções avançadas de API.

Como criar um provedor de tipos

Para criar um provedor de tipos, faça uma solicitação ao Deployment Manager com um payload contendo o nome do provedor de tipos desejado, o URL do descritor e todas as credenciais de autenticação necessárias.

gcloud

Para criar um provedor de tipos usando a CLI gcloud, use o comando type-providers create:

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

onde:

[TYPE_PROVIDER_NAME] é o nome que você quer dar ao tipo;
[URL] é o URL totalmente qualificado para acessar o documento descritor compatível com o tipo. Exemplo:
```
http://petstore.swagger.io/v2/swagger.json
```

Se você quiser fornecer credenciais de autenticação ou opções avançadas de API , crie um arquivo de opções de API escrito em YAML e forneça-o usando a sinalização --api-options-file. Por exemplo, o arquivo pode ser do seguinte modo:

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 você quiser autenticar usando uma autoridade de certificação (CA, na sigla em inglês) personalizada, poderá adicionar a CA como uma sinalização ao comando gcloud, como no exemplo a seguir:

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, crie uma solicitação POST no corpo da solicitação, contendo as opções de configuração descriptorUrl e uma opcional. 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.

Como testar o provedor de tipos

Para verificar se o provedor de tipos está funciona corretamente:

Faça uma chamada para o novo provedor de tipos em uma configuração.
Implante todas as coleções fornecidas pelo provedor de tipos para ter certeza de que a API está funcionando corretamente. Uma coleção é um recurso de API do provedor de tipos especificado.
Atualize todas as coleções.
Exclua todas as coleções.

Quando um usuário cria uma instância de um tipo do seu provedor de tipos, na realidade ele está fazendo uma solicitação ao Deployment Manager e não explicitamente à API de base. Por sua vez, o Deployment Manager cria a solicitação com as informações fornecidas para fazer uma solicitação à API em nome do usuário. O problema mais comum é que a API tenha propriedades que sejam de reconhecimento automático difícil pelo Deployment Manager. Por exemplo, algumas APIs requerem propriedades que só podem ser extraídas de uma resposta da API. Outras podem usar o mesmo nome de campo com valores diferentes, dependendo da operação. Nesses casos, você precisará instruir explicitamente o Deployment Manager sobre como lidar com essas situações.

Se a API tiver alguma dessas características, use mapeamentos de entrada para esclarecer a ambiguidade para o Deployment Manager.

A seguir

Saiba como chamar um provedor de tipos.
Compartilhar seu provedor de tipos com outros projetos.
Saiba mais sobre tipos.
Leia sobre como criar uma configuração.
Criar uma implantação.
Saiba mais sobre as Opções avançadas de API.