Importar metadados OData do SAP como uma API

APLICA-SE A: todas as camadas do Gerenciamento de API

Este artigo mostra como importar um serviço OData usando a respectiva descrição de metadados. Neste artigo, a SAP Gateway Foundation serve como exemplo.

Neste artigo, você vai:

• Recuperar metadados de OData do seu serviço SAP
• Importar metadados de OData para API Management, seja diretamente ou após a conversão para uma especificação de OpenAPI
• Concluir a configuração de API
• Testar a API no Portal do Azure

Observação

A importação de uma API OData para o API Management a partir de sua descrição de metadados está em versão preliminar. Saiba mais.

Pré-requisitos

• Uma instância de Gerenciamento de API existente. Crie uma, se ainda não tiver.

• Um sistema SAP e um serviço exposto como OData v2 ou v4.

• Se o seu back-end do SAP usar um certificado autoassinado (para fins de teste), talvez seja necessário desabilitar a verificação da cadeia de confiança para SSL. Para fazer isso, configure um back-end em sua instância do Gerenciamento de API:

  1. Na portal do Azure, em APIs, selecione back-ends>+ Adicionar.
  2. Adicione uma URL personalizada apontando para o serviço de back-end do SAP.
  3. Desmarque as opções Validar cadeia de certificados e Validar nome do certificado.

  Observação

  Para cenários de produção, use certificados apropriados para verificação de SSL de ponta a ponta.

Recuperar metadados de OData do seu serviço SAP

Recupere o XML de metadados de seu serviço SAP, usando um dos seguintes métodos. Se você planeja converter o XML de metadados em uma especificação de OpenAPI, salve o arquivo localmente.

• Use o cliente de gateway SAP (transação /IWFND/GW_CLIENT) ou
• Faça uma chamada HTTP direta para recuperar o XML: http://<OData server URL>:<port>/<path>/$metadata

Navegar até a instância de Gerenciamento de API

1. No portal do Azure, pesquise e selecione serviços de Gerenciamento de API.

   

2. Na página Serviços de Gerenciamento de API, selecione a sua instância de Gerenciamento de API.

   

Importar API para o API Management

Escolha um dos seguintes métodos para importar sua API para o API Management: importar o XML de metadados como uma API OData diretamente ou converter o XML de metadados em uma especificação de OpenAPI.

Metadados de OData

Importar metadados do OData

1. No menu à esquerda, selecione APIs>+ Adicionar API.

2. Em Criar com base na definição, selecione OData.

   

3. Insira as configurações de API. Você pode atualizar suas configurações mais tarde acessando a guia Configurações da API.

   1. Na especificação OData, insira uma URL para um ponto de extremidade de metadados OData, normalmente a URL para a raiz do serviço, acrescentada de /$metadata. Como alternativa, selecione um arquivo XML OData local a ser importado.

   2. Insira as configurações restantes para configurar sua API. Essas configurações são explicadas no tutorial Importar e publicar sua primeira API.

4. Selecione Criar.

   A API é adicionada à lista de APIs . Os conjuntos de entidades e as funções expostas na descrição de metadados do OData são exibidos na guia Conjuntos de entidades e funções da API.

   

Atualizar o esquema OData

Você pode acessar um editor no portal para exibir o esquema da API OData. Se a API for alterada, você também poderá atualizar o esquema em Gerenciamento de API de um arquivo ou de um ponto de extremidade de serviço OData.

1. No portal do Azure, navegue até a instância do Gerenciamento de API.

2. No menu à esquerda, selecione sua API OData APIs.

3. Na guia Conjuntos de entidades e funções, selecione o menu de contexto (…) ao lado de um conjunto de entidades ou de uma função e escolha Editar.

   

4. Examine o esquema. Se você quiser atualizá-lo, selecione Atualizar do arquivo ou Atualizar esquema do ponto de extremidade.

   

Testar a API OData

1. No menu à esquerda, selecione sua API OData APIs.

2. Na guia Conjuntos de entidades e funções, selecione o menu de contexto (…) ao lado de um conjunto de entidades ou de uma função e escolha Testar.

   

3. No console de teste, insira os parâmetros de modelo, os parâmetros de consulta e os cabeçalhos do teste e selecione Testar. Saiba mais sobre como testar uma API no portal.

Proteger sua API OData

Proteja sua API OData aplicando políticas de autenticação e autorização existentes e uma política de validação OData para protegê-la contra ataques por meio de solicitações de API OData.

Dica

No portal, configure políticas para sua API OData na guia Políticas de API .

Especificação OpenAPI

Converter metadados OData para JSON de OpenAPI

1. Converta o XML OData em formato JSON de OpenAPI. Use uma ferramenta de código-fonte aberto OASIS para OData v2 ou OData v4, dependendo do XML de metadados.

   Este é um exemplo de comando para converter o XML do OData v2 para o serviço de teste epm_ref_apps_prod_man_srv:

   odata-openapi -p --basePath '/sap/opu/odata/sap/epm_ref_apps_prod_man_srv' \
    --scheme https --host <your IP address>:<your SSL port> \
    ./epm_ref_apps_prod_man_srv.xml
   

   Observação

   • Para fins de teste com apenas um arquivo XML, você pode usar um conversor baseado na Web baseado na ferramenta de código-fonte aberto.
   • Com a ferramenta ou o conversor baseado na Web, especificar o < endereço IP>: <porta> do seu servidor SAP OData é opcional. Como alternativa, adicione essas informações posteriormente em sua especificação OpenAPI gerada ou depois de importar para o Gerenciamento de API.

2. Salve o arquivo openapi-spec.json localmente para importá-lo para o Gerenciamento de API.

Importar e publicar uma API de back-end

1. No menu de navegação lateral, na seção APIs, selecione APIs.

2. Em Criar uma definição, selecione Especificação de OpenAPI.

   

3. Clique em selecionar um arquivo e selecione o arquivo openapi-spec.json que você salvou localmente em uma etapa anterior.

4. Insira as configurações de API. Você pode definir os valores durante a criação ou configurá-los mais tarde, acessando a guia Configurações.

   • No sufixo de URL da API, é recomendável usar o mesmo caminho de URL do serviço SAP original.

   • Para obter mais informações sobre configurações de API, confira o tutorial Importar e publicar sua primeira API.

5. Selecione Criar.

Observação

As limitações de importação da API estão documentadas em outro artigo.

Concluir a configuração de API

Adicione as três operações a seguir à API que você importou.

• GET /$metadata

  Operação	Descrição	Configuração adicional para a operação
  GET /$metadata	Permite que o Gerenciamento de API alcance o ponto de extremidade $metadata, que é necessário para a integração de cliente com o servidor OData. Essa operação necessária não está incluída na especificação OpenAPI que você gerou e importou.	Adicione uma resposta 200 OK.

  

• HEAD /

  Operação	Descrição	Configuração adicional para a operação
  HEAD /	Habilita o cliente a trocar tokens de CSRF (solicitação intersite forjada) com o servidor SAP, quando necessário. O SAP também permite a troca de tokens CSRF usando o verbo GET. A troca de token CSRF não é abordada neste artigo. Confira um exemplo de trecho de política de Gerenciamento de API para troca de token do agente.	N/D

  

• GET /

  Operação	Descrição	Configuração adicional para a operação
  GET /	Habilita a configuração de política na raiz do serviço.	Configure a seguinte política rewrite-uri de entrada para acrescentar uma barra à direita às solicitações que são encaminhadas para a raiz do serviço: <rewrite-uri template="/" copy-unmatched-params="true" /> Essa política remove a possível ambiguidade de solicitações com ou sem barras à direita, que são tratadas de maneira diferente por alguns back-ends.

  

Além disso, configure a autenticação para seu back-end usando um método apropriado para seu ambiente. Para obter exemplos, consulte Políticas de autenticação e autorização do Gerenciamento de API.

Testar sua API

1. Navegue até sua instância de Gerenciamento de API.

2. No menu de navegação lateral, na seção APIs, selecione APIs.

3. Em Todas as APIs, selecione a API importada.

4. Selecione a guia Teste para acessar o console de teste.

5. Selecione uma operação, insira os valores necessários e selecione Enviar.

   Por exemplo, teste a chamada GET /$metadata para verificar a conectividade com o back-end do SAP

6. Exiba a resposta. Para solucionar problemas, rastreie a chamada.

7. Quando o teste for concluído, saia do console de teste.

Considerações sobre produção

• Veja um exemplo de cenário de ponta a ponta para integrar o Gerenciamento de API com um gateway SAP.
• Controle o acesso a um back-end do SAP usando políticas de Gerenciamento de API. Por exemplo, se a API for importada como uma API OData, use a política validar solicitação de OData. Consulte também os trechos de política para propagação da entidade de segurança do SAP e obtenção de um token X-CSRF.
• Para obter diretrizes de como implantar, gerenciar e migrar APIs em escala, confira:
  • Implantações de API automatizadas com APIOps
  • CI/CD para Gerenciamento de API usando modelos do Azure Resource Manager.

Tópicos relacionados

• Limitações de importação da API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importar uma API SOAP e converter em REST
• Importar uma API do Serviço de Aplicativo
• Importar uma API do Aplicativo de Contêiner
• Importar uma API WebSocket
• Importar uma API do GraphQL
• Importar um esquema do GraphQL e configurar resolvedores de campo
• Importar um Aplicativo de Funções do Azure
• Importar um Aplicativo Lógico do Azure
• Importar um serviço do Service Fabric
• Importar uma API de OData
• Importar metadados do SAP OData
• Importar uma API do gRPC
• Editar uma API