Configurar e testar a integração HTTP genérica para APIs HTTP do SAP

Pré-requisitos

• Servidor de integração implantado e registrado na plataforma que possa se conectar à API HTTP do SAP

• Dados do SAP disponíveis por meio de chamadas HTTP padrão

• Acesso a Asset Settings no RealityPlatform

• Documento OpenAPI que descreva a API HTTP (v2.0, v3.0 ou v3.1)

  • O documento pode ser YAML ou JSON

  • O documento pode ser armazenado localmente dentro da pasta Assets do servidor de integração, ou pode ser um S3 URI

Etapas de configuração

Este guia descreve como configurar a integração HTTP genérica para recuperar dados em um RealityAsset.

As principais etapas para configurar a integração HTTP são as seguintes:

1. Registrar a fonte de dados HTTP no RealityPlatform

2. Vincular a integração a um Asset Type

3. Enviar uma consulta de teste para validar a conexão com a API

Considerações especiais para sistemas sem conectores diretos

Embora este guia use o SAP como exemplo de referência, a mesma abordagem se aplica a qualquer sistema que não tenha um conector direto, mas que possa expor seus dados por HTTP.

Nesses casos, é prática comum usar um HTTP wrapper (ou API gateway) que exponha os dados do sistema por meio de chamadas HTTP padrão. Muitas plataformas empresariais — incluindo os produtos SAP — oferecem recursos integrados ou complementares para isso, mas qualquer solução equivalente pode ser usada.

Requisitos de integração:

• Autenticação baseada em token deve ser suportada.

• Requisições GET são preferidas para recuperar dados, embora outros verbos HTTP e métodos de autenticação venham a ser suportados no futuro.

• É necessário um documento OpenAPI (versão 2.0, 3.0 ou 3.1) que descreva a API

Registrar a fonte de dados HTTP no servidor de integração

• Adicione a nova fonte de dados

• Selecione o tipo HTTP

• Preencha os parâmetros obrigatórios para estabelecer a conexão

Parâmetros da fonte de dados HTTP

{
  "type": "HTTP",
  "name": "Example HTTP Data Source",
  "baseUrl": "https://example.com",
  "allowInsecure": false,
  "authBearerToken": "exampleBearerToken",
  "authBasic": "exampleBasicAuth",
  "schemaFile": "path/to/openapi/specification",
  "customAuthenticationHeader": {
    "Custom-Header": "HeaderValue"
  }
}

baseUrl

A URL base da fonte de dados HTTP.

allowInsecure

Permite que o servidor de integração consulte servidores web com certificados inválidos ou autoassinados.

schemaFile

O arquivo de esquema que descreve a API HTTP.

authBearerToken (Opcional)

O bearer token para autenticação, se aplicável.

authBasic (Opcional)

As informações de autenticação básica, se aplicável.

customAuthenticationHeader (Opcional)

Um cabeçalho de autenticação personalizado como um registro de pares chave-valor, se aplicável.

Nota

• A especificação OpenAPI pode ser disponibilizada dentro do serviço de integração e o caminho deve estar no parâmetro de configuração “schemaFile”. A maneira mais fácil de fazer isso é armazenar o arquivo no sistema de arquivos interno do serviço de integração e simplesmente fornecer o caminho relativo na configuração.

• Também é possível armazenar a especificação OpenAPI no AWS S3 e fornecer o S3 URI ao servidor de integração. Você deve garantir que o servidor de integração possa ler o documento do AWS S3.

Vincular propriedades de Asset Type ao HTTP

Antes de vincular, certifique-se de ter:

• Um Asset Type existente com uma propriedade para armazenar os valores de parâmetro HTTP exigidos (por exemplo, Asset ID). Deve ser uma propriedade do tipo “Short text”.

• Um servidor de integração configurado com uma fonte de dados HTTP e consultas.

Para vincular uma propriedade de Asset Type ao HTTP:

1. Em Asset Settings → Asset Types, abra o Asset Type que deseja vincular.

2. No painel Integration Links (lado direito), clique em Create Integration Link.

   

3. Insira um nome de link e selecione o servidor de integração configurado para o AWS IOT SiteWise.

4. Escolha a fonte de dados apropriada

5. Escolha a consulta desejada

6. Para cada parâmetro obrigatório (por exemplo, id), selecione a propriedade do Asset Type que deve fornecer seu valor (por exemplo, Id).

   

7. Clique em Save para criar o link.

Quando este Asset Type for atribuído a ativos, os valores das propriedades vinculadas serão automaticamente passados via HTTP ao executar a integração.

Enviar uma consulta de teste para validar a conectividade entre o RealityPlatform e a fonte de dados HTTP

1. Na página de configurações do Asset Type, clique no botão de reprodução ao lado do link de integração que aponta para a fonte de dados HTTP. Isso abrirá o menu de consulta de teste.

2. Insira um parâmetro válido na configuração de Parameters e clique em Test query para ver o resultado. Se nenhum parâmetro for necessário para o HTTP, a requisição será executada automaticamente e o resultado será exibido.

Nota

• Os valores inseridos aqui são apenas para fins de teste. Eles não são salvos no Asset Type nem nos ativos vinculados. Este teste simula o que o RealityTwin fará quando um ativo é criado, recebe este Asset Type e a propriedade correspondente (por exemplo, id) é preenchida. Use qualquer parâmetro válido para validar a conectividade.