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
- Para criar um conjunto de dados de referência, consulte Como criar um conjunto de dados de referência.
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-12Exemplo 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-12Exemplo 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-12Exemplo 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-12Exemplo 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-12Exemplo 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 http status 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 | Branca | 2 |
Quando os dois eventos na mensagem do hub de eventos são processados pelo mecanismo de entrada do 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) |
| Máximo de transações simultâneas | 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 aplicativo 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 auxiliam no teste de 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 solicitação HTTP e resposta para depuração de APIs REST.
Saiba mais sobre Azure Time Series Insights Gen1 examinando a documentação do Gen1.