API de Dados de Referência Azure Time Series Insights Gen1
Atenção
Este é um artigo da Gen1.
Este artigo descreve a API de referência Gestão de Dados Azure Time Series Insights Gen1 utilizada para gerir itens num conjunto de dados de referência. Pressupõe que o conjunto de dados de referência já foi criado no ambiente.
Os dados de referência incluem dados do fabricante ou da localização que são alterados com pouca frequência. Os dados de referência são utilizados para contextualizar dados telemétricos e servem para comparar dados telemétricos.
Dica
- Para criar um conjunto de dados de referência, veja Como criar um conjunto de dados de referência.
Uma vez que os conjuntos de dados são pré-existentes e corrigidos, cada pacote de dados enviado por um dispositivo conteria informações idênticas. Consequentemente, os dados de referência não são enviados a partir de dispositivos e pode gerir os dados com a API de referência Gestão de Dados ou a portal do Azure.
Descrição geral da API
A API de referência Gestão de Dados é uma API de lote.
Importante
- Todas as operações nesta API são operações HTTP POST.
- Cada operação aceita objetos JSON como payload do pedido.
- Os objetos JSON de pedido HTTP definem um nome de propriedade único que especifica a operação a ser executada pela API.
Os nomes de propriedade da operação de pedido JSON válidos são:
Importante
- O valor da propriedade é uma matriz de itens de dados de referência sobre os quais a operação tem de ser aplicada.
- Cada item é processado individualmente e um erro com um item não impede que os outros sejam escritos com êxito. Por exemplo, se o seu pedido tiver 100 itens e um item tiver um erro, 99 itens são escritos e um é rejeitado.
- Os itens de dados de referência são consultados com as respetivas propriedades de chave totalmente enumeradas.
Nota
Todos os exemplos de corpo JSON seguintes assumem um conjunto de dados de referência com uma única chave de propriedade com deviceId de nome e escreva Cadeia.
Colocar itens de dados de referência
Insere ou substitui todo o item $.put[i] de dados de referência (o ith item na matriz com a chave colocada). A unidade de consolidação é $.put[i]. A operação é idempotente.
Ponto final e operação:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Exemplo do corpo do pedido:
{ "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 patches
Atualizações e insere propriedades específicas para o item $.patch[i]de dados de referência .
Ponto final e operação:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Exemplo do corpo do pedido:
{ "patch": [ { "deviceId": "Fan1", "maxSpeed": 108 }, { "deviceId": "Fan2", "floor": 18 } ] }Exemplo do corpo da resposta:
{ "patch": [ null, null ] }
Eliminar propriedades em itens de dados de referência
Elimina as propriedades especificadas do item $.deleteproperties[i]de dados de referência .
Ponto final e operação:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Exemplo do corpo do pedido:
{ "deleteProperties":[ { "key":{ "deviceId":"Fan2" }, "properties":[ "floor" ] } ] }Exemplo do corpo da resposta:
{ "deleteProperties": [ null ] }
Eliminar itens de dados de referência
Elimina todo o item de dados de referência identificado pelos valores de propriedade de chave especificados em cada $.delete[i].
Ponto final e operação:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Exemplo do corpo do pedido:
{ "delete": [{ "deviceId": "Fan1" }] }Exemplo do corpo da resposta:
{ "delete": [ null ] }
Obter itens de dados de referência
Obtém todo o item de dados de referência que é identificado pelos valores de propriedade de chave especificados em cada $.get[i].
Ponto final e operação:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12Exemplo do corpo do pedido:
{ "get": [{ "deviceId": "Fan1" }, { "deviceId": "Fan2" }] }Exemplo do corpo da resposta:
{ "get": [ { "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }, { "id": "Fan2", "floor": 18 } ] }
Validação e processamento de erros
A API de referência Gestão de Dados processa cada item individualmente e um erro com um item não impede que os outros sejam escritos com êxito. Por exemplo, se o seu pedido tiver 100 itens e um item tiver um erro, 99 itens são escritos e um é rejeitado.
Códigos de erro do item
Os códigos de erro de itens ocorrem num corpo de resposta JSON com êxito que tem o código de estado 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 payload não deve conter nenhuma propriedade não chave.: indica que os itens de consulta do corpo do pedido JSON não devem conter quaisquer propriedades que não sejam propriedades chave (ou seja, propriedades especificadas no esquema do conjunto de referência). As propriedades da 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 da chave.: indica que os itens de consulta do corpo do pedido JSON devem incluir todas as propriedades de chave (ou seja, propriedades especificadas no esquema do conjunto de referência). As propriedades principais podem ser encontradas no portal do Azure.
{ "code": "InvalidInput", "message": "Payload item should contain all key properties.", "target": null, "details": null, "innerError": null }
Exemplo de associação de dados de referência
Considere uma mensagem do hub de eventos com 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 o deviceId chave do tipo Cadeia e que tem a seguinte estrutura:
| deviceId | color | maxSpeed | piso |
|---|---|---|---|
| Ventilador1 | Red | 5 | |
| Ventilador2 | Branco | 2 |
Quando os dois eventos na mensagem do hub de eventos são processados pelo motor de entrada Azure Time Series Insights Gen1, são associados ao item de dados de referência correto. A saída dos 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 associação e semântica
Ao associar dados de referência, cumpra as seguintes restrições:
- A comparação de nomes de chaves é sensível às maiúsculas e minúsculas.
- A comparação de valores-chave é sensível às maiúsculas e minúsculas das propriedades da cadeia.
Para ambientes com mais do que um conjunto de dados de referência, são impostas mais três restrições durante as associações:
- Cada item num conjunto de dados de referência pode especificar a 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 podem intercalar.
- Os conjuntos de dados de referência são associados diretamente apenas a eventos, nunca a outros conjuntos de dados referenciados (e, em seguida, a eventos). Para associar um item de dados de referência a um evento, todas as propriedades principais utilizadas no item de dados de referência têm de estar presentes no evento. Além disso, as propriedades de chave não devem ser provenientes das propriedades não chave que estão associadas a um evento através de outro item de dados de referência.
Dadas estas restrições, o motor de associação pode aplicar a associação em qualquer ordem para um determinado evento. A hierarquia e a ordenação não são consideradas.
Limites atuais
Pode adicionar até dois conjuntos de dados de referência por Azure Time Series Insights ambiente Gen1. As limitações adicionais associadas aos dados de referência do Azure Time Series Insights Gen1 estão listadas na seguinte tabela:
| Nome do limite | Valor de limite | SKUs afetados | Notas |
|---|---|---|---|
| Contagem de propriedades de chave | 3 | S1, S2 | Por conjunto de dados de referência; Apenas a Resource Manager do Azure e a 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 | 2000/20 000 (S1/S2) | S1, S2 | Por unidade; por exemplo, SKU S1 de 4 unidades = 8000 itens (4 x 2 000) |
| Máximo de transações simultâneas | 10/2 (S1/S2) | S1, S2 | |
| Máximo de transações 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 |
Ver também
Para obter mais informações sobre o registo de aplicações e o modelo de programação do Azure Active Directory, veja Azure Active Directory para programadores.
Para saber mais sobre os parâmetros de pedido e autenticação, veja Autenticação e autorização.
As ferramentas que ajudam a testar pedidos e respostas HTTP incluem:
- Fiddler. Este proxy de depuração Web gratuito pode intercetar os seus pedidos REST, para que possa diagnosticar as mensagens de pedido e resposta HTTP.
- JWT.io. Pode utilizar esta ferramenta para capturar rapidamente as afirmações no token de portador e, em seguida, validar os respetivos conteúdos.
- Postman. Esta é uma ferramenta de teste de resposta e pedido HTTP gratuita para depurar APIs REST.
Saiba mais sobre Azure Time Series Insights Gen1 ao rever a documentação do Gen1.