API de Dados de Referência do Azure Time Series Insights Gen1

Cuidado

Esse é um artigo do Gen1.

Este artigo descreve a API Gerenciamento de Dados de Referência do Azure Time Series Insights Gen1 usada para gerenciar itens em um conjunto de dados de referência. Ele pressupõe que o conjunto de dados de referência já tenha sido criado dentro do ambiente.

Os dados de referência incluem dados de fabricante ou local que são alterados com pouca frequência. Os dados de referência são usados para contextualizar dados de telemetria e servem para comparar dados de telemetria.

Dica

Como os conjuntos de dados são preexistenciais e fixos, cada pacote de dados enviado por um dispositivo conteria informações idênticas. Consequentemente, os dados de referência não são enviados de dispositivos e você gerencia os dados usando a API Gerenciamento de Dados de Referência ou o portal do Azure.

Visão geral da API

A API de Gerenciamento de Dados de Referência é uma API de lote.

Importante

  • Todas as operações nessa API são operações HTTP POST.
  • Cada operação aceita objetos JSON como o conteúdo da solicitação.
  • Os objetos JSON de solicitação HTTP definem um único nome de propriedade que especifica a operação a ser executada pela API.

Os nomes de propriedade válidos da operação de solicitação JSON são:

Importante

  • O valor da propriedade é uma matriz de itens de dados de referência sobre os quais a operação deve ser aplicada.
  • Cada item é processado individualmente e um erro com um item não impede que os outros sejam gravados com êxito. Por exemplo, se sua solicitação tiver 100 itens e um item tiver um erro, 99 itens serão gravados e um será rejeitado.
  • Os itens de dados de referência são consultados usando suas propriedades de chave totalmente enumeradas.

Observação

Todos os exemplos de corpo JSON a seguir pressupõem um conjunto de dados de referência com uma única chave de propriedade com o nome deviceId e o tipo String.

Colocar itens de dados de referência

Insere ou substitui todo o item $.put[i] de dados de referência (o i th item na matriz pela chave put). A unidade de confirmação é $.put[i]. A operação é idempotente.

  • Ponto de extremidade e operação:

    POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
    
  • Exemplo de corpo da solicitação:

    {
      "put": [{
        "deviceId": "Fan1",
        "color": "Red",
        "maxSpeed": 5
      },
      {
        "deviceId": "Fan2",
        "color": "White",
        "floor": 2
      }]
    }
    
  • Exemplo de resposta:

    {
      "put": [
        null,
        null
      ]
    }
    

Itens de dados de referência de patch

Atualizações e insere propriedades específicas para o item $.patch[i]de dados de referência .

  • Ponto de extremidade e operação:

    POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
    
  • Exemplo de corpo da solicitação:

    {
      "patch": [
        {
          "deviceId": "Fan1",
          "maxSpeed": 108
        },
        {
          "deviceId": "Fan2",
          "floor": 18
        }
      ]
    }
    
  • Exemplo de corpo da resposta:

    {
      "patch": [
        null,
        null
      ]
    }
    

Excluir propriedades em itens de dados de referência

Exclui as propriedades especificadas do item $.deleteproperties[i]de dados de referência .

  • Ponto de extremidade e operação:

    POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
    
  • Exemplo de corpo da solicitação:

    {
      "deleteProperties":[
        {
          "key":{
            "deviceId":"Fan2"
          },
          "properties":[
            "floor"
          ]
        }
      ]
    }
    
  • Exemplo de corpo da resposta:

    {
      "deleteProperties": [
        null
      ]
    }
    

Excluir itens de dados de referência

Exclui todo o item de dados de referência identificado pelos valores de propriedade de chave especificados em cada $.delete[i].

  • Ponto de extremidade e operação:

    POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
    
  • Exemplo de corpo da solicitação:

    {
      "delete": [{
        "deviceId": "Fan1"
      }]
    }
    
  • Exemplo de corpo da resposta:

    {
      "delete": [
        null
      ]
    }
    

Obter itens de dados de referência

Obtém todo o item de dados de referência identificado pelos valores de propriedade de chave especificados em cada $.get[i].

  • Ponto de extremidade e operação:

    POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
    
  • Exemplo de corpo da solicitação:

    {
      "get": [{
        "deviceId": "Fan1"
      },
      {
        "deviceId": "Fan2"
      }]
    }
    
  • Exemplo de corpo da resposta:

    {
      "get": [
        {
          "code": "InvalidInput",
          "message": "Key not found.",
          "target": null,
          "details": null,
          "innerError": null
        },
        {
          "id": "Fan2",
          "floor": 18
        }
      ]
    }
    

Validação e tratamento de erros

A API Gerenciamento de Dados de Referência processa cada item individualmente e um erro com um item não impede que os outros sejam gravados com êxito. Por exemplo, se sua solicitação tiver 100 itens e um item tiver um erro, 99 itens serão gravados e um será rejeitado.

Códigos de erro de item

Os códigos de erro de item ocorrem em um corpo de resposta JSON bem-sucedido que tem o código de status HTTP 200.

  • InvalidInput: chave não encontrada.: indica que o item consultado não pode ser encontrado no conjunto de dados de referência.

    {
      "code": "InvalidInput",
      "message": "Key not found.",
      "target": null,
      "details": null,
      "innerError": null
    }
    
  • InvalidInput: a chave de payload não deve conter nenhuma propriedade não chave.: indica que os itens de consulta do corpo da solicitação JSON não devem conter nenhuma propriedade que não sejam propriedades de chave (ou seja, propriedades especificadas no esquema do conjunto de referência). As propriedades de chave podem ser encontradas no portal do Azure.

    {
      "code": "InvalidInput",
      "message": "Payload key should not contain any non-key property.",
      "target": null,
      "details": null,
      "innerError": null
    }
    
  • InvalidInput: o item payload deve conter todas as propriedades de chave.: indica que os itens de consulta do corpo da solicitação JSON devem incluir todas as propriedades de chave (ou seja, propriedades especificadas no esquema do conjunto de referência). As propriedades de chave podem ser encontradas em portal do Azure.

    {
      "code": "InvalidInput",
      "message": "Payload item should contain all key properties.",
      "target": null,
      "details": null,
      "innerError": null
    }
    

Exemplo de junção de dados de referência

Considere uma mensagem do hub de eventos que tenha a seguinte estrutura:

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z"
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z"
  }
]

Considere um item de dados de referência definido com o nome contoso e a chave deviceId do tipo String e que tenha a seguinte estrutura:

deviceId cor Maxspeed floor
Fan1 Vermelho 5
Fan2 Branco 2

Quando os dois eventos na mensagem do hub de eventos são processados pelo mecanismo de entrada Azure Time Series Insights Gen1, eles são unidos ao item de dados de referência correto. A saída de eventos tem a seguinte estrutura:

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"Red",
    "maxSpeed":5
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"White",
    "floor":2
  }
]

Regras de junção e semântica

Ao unir dados de referência, siga as seguintes restrições:

  • A comparação de nomes de chave diferencia maiúsculas de minúsculas.
  • A comparação de valor de chave diferencia maiúsculas de minúsculas para propriedades de cadeia de caracteres.

Para ambientes com mais de um conjunto de dados de referência, três restrições adicionais são impostas durante as junções:

  • Cada item em um conjunto de dados de referência pode especificar sua própria lista de propriedades não chave.
  • Para os dois conjuntos de dados de referência A e B, as propriedades não chave não devem se cruzar.
  • Os conjuntos de dados de referência são unidos diretamente somente a eventos, nunca a outros conjuntos de dados referenciados (e, em seguida, a eventos). Para unir um item de dados de referência a um evento, todas as principais propriedades usadas no item de dados de referência devem estar presentes no evento. Além disso, as propriedades de chave não devem vir das propriedades não chave que são unidas a um evento por meio de algum outro item de dados de referência.

Dadas essas restrições, o mecanismo de junção pode aplicar a junção em qualquer ordem para um determinado evento. Hierarquia e ordenação não são consideradas.

Limites atuais

Você pode adicionar até dois conjuntos de dados de referência por ambiente Azure Time Series Insights Gen1. Limitações adicionais associadas aos dados de referência do Azure Time Series Insights Gen1 estão listadas na tabela a seguir:

Nome do limite Valor de limite SKUs afetadas Observações
Contagem de propriedades de chave 3 S1, S2 Por conjunto de dados de referência; Somente Resource Manager do Azure e o portal do Azure
Tamanho da propriedade da chave 1 KB S1, S2 Conjunto de dados por referência
Contagem de itens de dados de referência 2.000/20.000 (S1/S2) S1, S2 Por unidade; por exemplo, SKU S1 de 4 unidades = 8.000 itens (4 x 2.000)
Transações simultâneas máximas 2/10 (S1/S2) S1, S2
Transações máximas de dados de referência 120/600 (S1/S2) S1, S2 Por hora
Contagem máxima de itens de dados de referência 1,000 S1, S2 Por transação
Tamanho máximo do item de dados de referência 8.192 KB S1, S2 Por transação

Confira também

Para obter mais informações sobre o registro de aplicativos e o modelo de programação do Azure Active Directory, consulte Azure Active Directory para desenvolvedores.

Para saber mais sobre os parâmetros de solicitação e autenticação, consulte Autenticação e autorização.

As ferramentas que ajudam a testar solicitações e respostas HTTP incluem:

  • Fiddler. Esse proxy de depuração da Web gratuito pode interceptar suas solicitações REST, para que você possa diagnosticar as mensagens de solicitação e resposta HTTP.
  • JWT.io. Você pode usar essa ferramenta para despejar rapidamente as declarações em seu token de portador e, em seguida, validar seu conteúdo.
  • O Postman. Essa é uma ferramenta gratuita de teste de resposta e solicitação HTTP para depuração de APIs REST.

Saiba mais sobre Azure Time Series Insights Gen1 examinando a documentação do Gen1.