Esta página foi traduzida pela API Cloud Translation.

Como criar um proxy de API de uma especificação da OpenAPI

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

O que você vai aprender

Neste tutorial, você aprenderá a:

Criar um proxy da API Apigee com base em uma especificação OpenAPI.
Chamar o proxy de API usando cURL.
Adicionar uma política a um fluxo condicional.
Testar a invocação da política usando cURL.

Você aprenderá como criar um proxy da API Apigee a partir de uma especificação OpenAPI usando a IU da Apigee. Quando você chama o proxy de API com um cliente HTTP, como cURL, o proxy de API envia a solicitação para o serviço de destino simulado da Apigee.

Sobre a Iniciativa de API aberta

"A Iniciativa de API aberta (OAI, na sigla em inglês) tem como foco criar, evoluir e promover um formato de descrição de API neutra de fornecedor com base na especificação Swagger." Para mais informações sobre a Open API Initiative, consulte A especificação OpenAPI.

Uma especificação OpenAPI usa um formato padrão para descrever uma API RESTful. Escrita em formato JSON ou YAML, uma especificação OpenAPI é legível por máquina, mas também é fácil de ler e entender por pessoas. A especificação descreve esses elementos de uma API como caminho base, caminhos e verbos, cabeçalhos, parâmetros de consulta, operações, tipos de conteúdo, descrições de resposta e muito mais. Além disso, uma especificação OpenAPI é comumente usada para gerar a documentação da API.

Sobre o serviço de destino simulado da Apigee

O serviço de destino simulado da Apigee usado neste tutorial está hospedado na Apigee e retorna dados simples. Ele não requer nenhuma chave de API nem um token de acesso. Na verdade, é possível acessá-lo em um navegador da Web. Para testar, clique no seguinte:

http://mocktarget.apigee.net

O serviço de destino retorna a saudação Hello, guest!

Para informações sobre o conjunto completo de APIs compatíveis com o serviço de destino simulado, consulte APIs de amostra da Apigee

Pré-requisitos

Antes de começar, é preciso concluir as etapas em Visão geral e pré-requisitos.
Uma especificação OpenAPI. Neste tutorial, você usará a especificação OpenAPI mocktarget.yaml, que descreve o serviço de destino simulado da Apigee http://mocktarget.apigee.net. Para mais informações, consulte apigee/api-platform-samples (em inglês).
cURL instalado na máquina para fazer chamadas de API pela linha de comando ou um navegador da Web.

Criar o proxy de API

Para criar o proxy de API com base em uma especificação OpenAPI:

Apigee no console do Cloud

No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.

Acessar proxies de API
No painel Proxy de API, clique em + Criar.
No painel Criar um proxy, em Modelo de proxy > Modelo de especificação OpenAPI, selecione Proxy reverso (mais comum).

Navegue até o seguinte URL no navegador da Web:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

Clique com o botão direito do mouse no código exibido e selecione Salvar como.
Clique em Salvar para salvar o mocktarget3.0.yaml no local desejado.
No campo Especificações da OpenAPI, clique no botão Procurar.
Navegue até o arquivo mocktarget3.0.yaml e clique em Abrir.
Clique em Próxima.
A etapa Detalhes do proxy do assistente Criar proxy preenche automaticamente os campos com valores extraídos diretamente da especificação OpenAPI.

A tabela a seguir descreve os valores padrão pré-preenchidos usando a especificação OpenAPI:

Campo	Descrição	Padrão
Nome do proxy	Nome do proxy de API. Por exemplo, `Mock-Target-API`.	Propriedade `title` da especificação OpenAPI com espaços substituídos por traços
Caminho base	Componente de caminho que identifica exclusivamente esse proxy de API na organização. O URL público desse proxy de API é composto pelo nome de domínio externo ou interno e neste caminho base. Por exemplo: `http://apitest.acme.com/mock-target-api`	Campo Nome convertido em letras minúsculas
Descrição	Descrição do proxy de API.	Propriedade `description` da especificação OpenAPI
Destino (API existente)	URL de destino invocado em nome deste proxy de API. Qualquer URL acessível por meio da Internet aberta pode ser usado. Por exemplo: `http://mocktarget.apigee.net`	Propriedade `servers` da especificação OpenAPI

Veja a seguir um trecho da especificação OpenAPI mostrando as propriedades usadas para preencher previamente os campos.

      openapi: 3.0.0
      info:
        description: OpenAPI Specification for the Apigee mock target service endpoint.
        version: 1.0.0
        title: Mock Target API
      paths:
        /:
          get:
            summary: View personalized greeting
            operationId: View a personalized greeting
            description: View a personalized greeting for the specified or guest user.
            parameters:
              - name: user
                in: query
                description: Your user name.
                required: false
                schema:
                  type: string
            responses:
              "200":
                description: Success
      ...
      servers:
        - url: http://mocktarget.apigee.net
        - url: https://mocktarget.apigee.net
      ...

Na etapa Detalhes do proxy, edite o campo Descrição da seguinte maneira:
```
API proxy for the Apigee mock target service endpoint.
```
Clique em Próxima.
Na etapa Fluxos, verifique se todas as operações estão selecionadas.
Dica:os fluxos condicionais são gerados automaticamente com base nas operações definidas no objeto paths na especificação OpenAPI. Os fluxos condicionais informam à Apigee o seguinte: "Ao ver isto, execute esta lógica." Por exemplo, quando uma chamada de API é GET no recurso /xml (a condição), ela transforma a resposta em JSON (por meio de uma política anexada ao fluxo condicional). Apenas um fluxo é executado por transação, o primeiro que tem uma condição avaliada como verdadeira.
Clique em Próxima.
Na etapa Implantar, selecione um ou mais ambientes e clique em OK.
Clique em Criar.

IU clássica da Apigee

Selecione Desenvolver > Proxies de API e, no painel Proxies, selecione o ambiente do proxy.
Clique em API Proxies na janela principal.
Como alternativa, selecione Develop > API Proxies na barra de navegação à esquerda.
Clique em Criar nova.
No assistente de criação de proxy, clique em Use OpenAPI Spec para o modelo Reverse proxy (most common).
Clique em URL e digite as seguintes informações:
OpenAPI Spec URL: caminho para o conteúdo bruto do GitHub para a especificação OpenAPI no campo URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```

Clique em Selecionar.

A página detalhes de proxy do assistente de criação de proxy é exibida. Os campos são pré-preenchidos com valores definidos na especificação OpenAPI, conforme mostrado na figura a seguir:

A tabela a seguir descreve os valores padrão pré-preenchidos usando a especificação OpenAPI:

Campo	Descrição	Padrão
Nome	Nome do proxy de API. Por exemplo, `Mock-Target-API`.	Propriedade `title` da especificação OpenAPI com espaços substituídos por traços
Caminho base	Componente de caminho que identifica exclusivamente esse proxy de API na organização. O URL público desse proxy de API é composto pelo nome de domínio externo ou interno e neste caminho base. Por exemplo: `http://apitest.acme.com/mock-target-api`	Campo Nome convertido em letras minúsculas
Descrição	Descrição do proxy de API.	Propriedade `description` da especificação OpenAPI
Destino (API existente)	URL de destino invocado em nome deste proxy de API. Qualquer URL acessível por meio da Internet aberta pode ser usado. Por exemplo: `http://mocktarget.apigee.net`	Propriedade `servers` da especificação OpenAPI

Veja a seguir um trecho da especificação OpenAPI mostrando as propriedades usadas para preencher previamente os campos.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Na página Detalhes do proxy, edite o campo Descrição da seguinte maneira:
```
API proxy for the Apigee mock target service endpoint.
```
Clique em Próxima.
Na página Common policies, em Security: Authorization verifique se a opção Pass through (no authorization) está selecionada e clique em Next:
Na página Fluxos, verifique se todas as operações estão selecionadas.
Dica: os fluxos condicionais são gerados automaticamente com base nas operações definidas no objeto paths na especificação OpenAPI. Os fluxos condicionais informam à Apigee o seguinte: "Ao ver isto, execute esta lógica." Por exemplo, quando uma chamada de API é GET no recurso /xml (a condição), ela transforma a resposta em JSON (por meio de uma política anexada ao fluxo condicional). Apenas um fluxo é executado por transação, o primeiro que tem uma condição avaliada como verdadeira.
Clique em Próxima.
Na página Resumo, verifique se um ambiente está selecionado em Implantação opcional e clique em Criar e implantar:

A Apigee cria seu novo proxy de API e o implanta no ambiente:
Clique em Edit proxy para exibir a página Visão geral do proxy de API.

Testar o proxy de API

É possível testar sua API Mock-Target-API usando cURL ou um navegador da Web.

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

em que YOUR_ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

Exemplo:

curl -v -k https://apitest.acme.com/myproxy

Resposta

Você verá a seguinte resposta:

Hello, Guest!

Adicionar uma política XML para JSON

Em seguida, adicione a política XML para JSON ao fluxo condicional View XML Response gerado automaticamente quando você criou o proxy de API com base na especificação OpenAPI. A política converterá a resposta XML do destino em uma resposta JSON.

Primeiro, chame a API para comparar os resultados com aqueles recebidos depois de adicionar a política. Em uma janela de terminal, execute o comando cURL a seguir. Você está chamando o recurso /xml do serviço de destino, que retorna nativamente um bloco simples de XML.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

em que YOUR ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

Resposta

Você verá a seguinte resposta:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Agora, vamos fazer algo para converter a resposta XML em JSON. Adicione a política XML para JSON ao fluxo condicional "View XML Response" no proxy de API.

Apigee no console do Cloud

Clique na guia Develop na página visão geral da API Mock-Target na IU da Apigee.

Selecionar "View XML Response"

No painel esquerdo do navegador, em Proxy Endpoints > default, clique no fluxo condicional View XML Response.
No painel à esquerda, clique no botão + na linha Políticas.
NaCriar política clique no botãoSelecionar tipo de política campo, role para baixo atéMediação e selecioneXMLToJSON. de dados. Mantenha os valores padrão de Display Name e Name.
Clique em Criar para criar a política.
Clique no botão + ao lado do fluxo View XML response no campo Response.
Na caixa de diálogo Add Policy Step, clique no campo Select existing policy e selecione XML to JSON-1.
Clique em Adicionar. A política XML para JSON é aplicada à resposta.

Para ver o código do fluxo condicional View XML Response, clique em Switch To Code Editor.
Clique em Salvar.

IU clássica da Apigee

Clique na guia Develop na página visão geral da API Mock-Target na IU da Apigee.
No painel esquerdo do navegador, em Proxy Endpoints > default, clique no fluxo condicional View XML Response.
Clique no botão +Step inferior, correspondente à Response do fluxo.

A caixa de diálogo Add Step é aberta para exibir uma lista categorizada de todas as políticas que podem ser adicionadas.
Role até a categoria Mediation e selecione XML to JSON.
Mantenha os valores padrão de Display Name e Name.
Clique em Adicionar. A política XML para JSON é aplicada à resposta.
Clique em Salvar.

Agora que você adicionou a política, chame novamente a API usando cURL. Observe que você ainda está chamando o mesmo recurso /xml. O serviço de destino ainda retorna o bloco de XML, mas agora a política no proxy de API converterá a resposta em JSON. Faça esta chamada:

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

em que YOUR ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

A resposta XML é convertida em JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Como criar um proxy de API de uma especificação da OpenAPI Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Pré-requisitos

Criar o proxy de API

Apigee no console do Cloud

IU clássica da Apigee

Testar o proxy de API

Adicionar uma política XML para JSON

Apigee no console do Cloud

IU clássica da Apigee

Como criar um proxy de API de uma especificação da OpenAPI