Descoberta por URL

Este assistente parte do endereço de uma API e devolve uma proposta de configuração. Ele é o generalista do conjunto: serve para qualquer sistema que fale HTTP, tenha ele documentação formal ou não.

Abre pelo ícone de varinha na linha da Aplicação, em Aplicações.

O que você pode informar

Uma URL, e opcionalmente um texto dizendo o que você quer daquela API.

Contratos reconhecidos

O tipo é detectado pelo conteúdo, não pela extensão — um Swagger servido em /api sem extensão nenhuma é reconhecido igual.

Caminhos que ele procura sozinho

Primeiro, o próprio endereço que você colou: se ele já é o contrato (.../$metadata, .../openapi.json, ...?wsdl), é ele que vale. Junto, o $metadata logo abaixo dele e o do nível acima — o caso de quem colou a raiz de um serviço OData ou a URL de um EntitySet.

Se nada disso responder, o CMS tenta os caminhos de convenção a partir do host e dos primeiros níveis do endereço: /openapi.json, /swagger.json, /api-json, /v3/api-docs, /swagger/v1/swagger.json, /api-docs e /$metadata — este em todos os níveis do caminho, porque a raiz de um serviço SAP fica fundo. Parâmetros como o sap-client vão junto.

OData

Informe a raiz do serviço, não só o host. Um host costuma publicar vários serviços — um SAP Gateway tem centenas —, e só a raiz de cada um tem $metadata. A URL de um EntitySet ou de uma entidade (.../Customers('ALFKI')) também serve: o CMS sobe até a raiz.

A versão vem do próprio $metadata, e a configuração segue as regras dela:

O que o serviço declara é respeitado: conjunto só de leitura (sap:creatable="false" no SAP, anotações Capabilities na v4) não ganha escrita, entidade de mídia não ganha criação por JSON, e o $format=json já vem nos Parâmetros Fixos da Coleta — sem ele o SAP responde em XML.

Aplicação SAP Gateway

Numa Aplicação do tipo SAP Gateway, a URL já abre como http://host:porta/sap/opu/odata/sap/ — complete com o serviço (PP_PRODOPS_CONFIRM_SRV/). Deixar só esse prefixo é recusado com uma mensagem clara: o SAP responderia 500 “Access using a ‘ZERO’ service”, porque ali não há serviço nenhum.

• A leitura do contrato usa o usuário e o mandante da conexão — ou a Credencial escolhida no assistente —, mas só quando a URL é o servidor da conexão. Para outro endereço, a chamada sai sem autenticação e sem seguir redirecionamento, para que ninguém receba o usuário do SAP digitando um endereço próprio.
• O campo Contrato aceita também a URL do contrato (.../PP_PRODOPS_CONFIRM_SRV/$metadata), que é baixado na hora. Se não der para baixar, a mensagem traz o status que o servidor devolveu.

A sondagem, e seus limites

Quando não há contrato, o CMS faz uma requisição real à URL para ver o que volta. Isso é uma chamada ao sistema do cliente, então ela é contida:

• somente GET — nada que altere estado;
• 10 segundos de tempo limite;
• 1 MB de resposta, no máximo;
• 3 redirecionamentos, no máximo;
• endereços de metadados de nuvem (o 169.254.169.254 da AWS/Azure/GCP e equivalentes) são bloqueados, para que uma URL colada por engano não vire leitura de credencial de instância.

De onde veio cada operação

Cada operação da lista traz uma etiqueta de procedência, e ela é o que separa o que o CMS sabe do que ele supõe:

Preste atenção especial nas INFERIDO na hora de revisar: são as que podem estar plausíveis e erradas ao mesmo tempo.

A lista de operações

Um Swagger de porte real traz centenas de operações. A lista é montada para isso:

• agrupada por cenário, com os grupos fechados e contagem em cada um;
• marcar / limpar o grupo inteiro de uma vez;
• filtro por direção (Coleta ou Entrega) e busca por texto — buscar abre os grupos sozinho;
• detalhe sob demanda: campos obrigatórios e exemplo de corpo são buscados quando você clica em “ver detalhe”, não para as 450 operações de uma vez.

Revisão e instalação

Antes de gravar, a revisão mostra cada objeto com CRIAR, ATUALIZAR ou CUSTOMIZADO, e permite renomear qualquer sigla ou apontar uma Interface existente no lugar da proposta.

Testar as leituras agora executa as Coletas escolhidas contra a API, no endereço e com os Parâmetros Fixos que elas terão, e mostra a resposta de cada uma. Entregas nunca são disparadas por ali — escreveriam no sistema de destino. Leitura que depende de um campo da mensagem (a chave de /OrdemSet('{{Aufnr}}')) só é testável com uma mensagem real.

A URL da Aplicação. A Coleta chama o endereço da Aplicação mais o caminho da operação. Se a Aplicação ainda não tem URL, ela recebe a URL base confirmada no assistente. Se tem só o host, as Coletas levam o caminho da raiz do serviço (/sap/opu/odata/sap/API_X_SRV/OrdemSet). URL em outro host não é trocada — é decisão de quem cadastrou a Aplicação (um proxy, outro ambiente) —, e então vale conferir o caminho das Coletas depois de instalar.

Depois de instalar, o assistente mostra o que foi criado com link para cada tela — Interfaces, Coletas, Entregas e Erros de Negócio. Como tudo nasce desativado, esse link é o próximo passo, não um detalhe.

Autenticação

Se a API exige credencial, cadastre-a antes em Credenciais e escolha-a no assistente. O CMS cobre Basic, Bearer, API Key, login com token e OAuth2 client credentials — este último com renovação automática, scope e parâmetros extras quando o provedor exige.