API de datos de referencia de Azure Time Series Insights Gen1

Artículo
07/19/2023

Precaución

Este es un artículo de Gen1.

En este artículo se describe la API de referencia de Azure Time Series Insights Gen1 Administración de datos que se usa para administrar elementos dentro de un conjunto de datos de referencia. Se supone que el conjunto de datos de referencia ya se ha creado en el entorno.

Los datos de referencia incluyen los datos de fabricante o ubicación que cambian con poca frecuencia. Los datos de referencia se usan para contextualizar los datos de telemetría y sirven para comparar los datos de telemetría.

Sugerencia

Para crear un conjunto de datos de referencia, consulte Creación de un conjunto de datos de referencia.

Dado que los conjuntos de datos están preexistentes y corregidos, cada paquete de datos enviado por un dispositivo contendrá información idéntica. Por lo tanto, los datos de referencia no se envían desde dispositivos y administra los datos mediante la API reference Administración de datos o el Azure Portal.

Introducción a la API

Reference Administración de datos API es una API por lotes.

Importante

Todas las operaciones en esta API son operaciones HTTP POST.
Cada operación acepta objetos JSON como carga de solicitud.
Los objetos JSON de solicitud HTTP definen un nombre de propiedad único que especifica la operación que va a ejecutar la API.

Los nombres de propiedad de la operación de solicitud JSON válidos son:

Poner
Revisión
Eliminar propiedades
Eliminar
Get

Importante

El valor de la propiedad es una matriz de elementos de datos de referencia sobre los que se debe aplicar la operación.
Cada elemento se procesa individualmente y un error con un elemento no impide que los demás se escriban correctamente. Por ejemplo, si la solicitud tiene 100 elementos y un elemento tiene un error, se escriben 99 elementos y se rechaza uno.
Los elementos de datos de referencia se consultan mediante sus propiedades de clave enumeradas por completo.

Nota:

Todos los siguientes ejemplos de cuerpo JSON asumen un conjunto de datos de referencia con una sola clave de propiedad con el nombre deviceId y el tipo String.

Colocar elementos de datos de referencia

Inserta o reemplaza todo el elemento $.put[i] de datos de referencia (el ^{elemento i ésima} de la matriz por la clave put). La unidad de confirmación es La operación es $.put[i]. idempotente.

Punto de conexión y operación:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Ejemplo de cuerpo de la solicitud:

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

Ejemplo de respuesta:
```
{
  "put": [
    null,
    null
  ]
}
```

Revisión de los elementos de datos de referencia

Novedades e inserta propiedades específicas para el elemento $.patch[i]de datos de referencia .

Punto de conexión y operación:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Ejemplo de cuerpo de la solicitud:

{
  "patch": [
    {
      "deviceId": "Fan1",
      "maxSpeed": 108
    },
    {
      "deviceId": "Fan2",
      "floor": 18
    }
  ]
}

Ejemplo de cuerpo de respuesta:

{
  "patch": [
    null,
    null
  ]
}

Eliminar propiedades en elementos de datos de referencia

Elimina las propiedades especificadas del elemento $.deleteproperties[i]de datos de referencia .

Punto de conexión y operación:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Ejemplo de cuerpo de la solicitud:

{
  "deleteProperties":[
    {
      "key":{
        "deviceId":"Fan2"
      },
      "properties":[
        "floor"
      ]
    }
  ]
}

Ejemplo de cuerpo de respuesta:

{
  "deleteProperties": [
    null
  ]
}

Eliminar elementos de datos de referencia

Elimina todo el elemento de datos de referencia identificado por los valores de propiedad de clave especificados en cada $.delete[i].

Punto de conexión y operación:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Ejemplo de cuerpo de la solicitud:

{
  "delete": [{
    "deviceId": "Fan1"
  }]
}

Ejemplo de cuerpo de respuesta:
```
{
  "delete": [
    null
  ]
}
```

Obtener elementos de datos de referencia

Obtiene todo el elemento de datos de referencia identificado por los valores de propiedad de clave especificados en cada $.get[i].

Punto de conexión y operación:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Ejemplo de cuerpo de la solicitud:

{
  "get": [{
    "deviceId": "Fan1"
  },
  {
    "deviceId": "Fan2"
  }]
}

Ejemplo de cuerpo de respuesta:

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

Validación y control de errores

La API Reference Administración de datos procesa cada elemento individualmente y un error con un elemento no impide que los demás se escriban correctamente. Por ejemplo, si la solicitud tiene 100 elementos y un elemento tiene un error, se escriben 99 elementos y se rechaza uno.

Códigos de error de elemento

Los códigos de error de elemento se producen dentro de un cuerpo de respuesta JSON correcto que tiene el código de estado HTTP 200.

InvalidInput: Clave no encontrada: indica que el elemento consultado no se encuentra en el conjunto de datos de referencia.
```
{
  "code": "InvalidInput",
  "message": "Key not found.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: la clave de carga no debe contener ninguna propiedad que no sea clave. Indica que los elementos de consulta del cuerpo de la solicitud JSON no deben contener propiedades que no sean propiedades clave (es decir, propiedades especificadas en el esquema del conjunto de referencia). Las propiedades clave se pueden encontrar en el Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: el elemento de carga debe contener todas las propiedades clave.: indica que los elementos de consulta del cuerpo de la solicitud JSON deben incluir todas las propiedades de clave (es decir, las propiedades especificadas en el esquema del conjunto de referencia). Las propiedades clave se pueden encontrar en Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload item should contain all key properties.",
  "target": null,
  "details": null,
  "innerError": null
}
```

Ejemplo de combinación de datos de referencia

Considere un mensaje del centro de eventos que tenga la estructura siguiente:

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

Considere un elemento de datos de referencia que se establece con el nombre contoso y el identificador de clave deviceId de tipo String y que tiene la estructura siguiente:

deviceId	color	maxSpeed	floor
Fan1	Rojo	5
Fan2	Blanco		2

Cuando Azure Time Series Insights motor de entrada de Gen1 procesan los dos eventos del mensaje del centro de eventos, se unen con el elemento de datos de referencia correcto. La salida de eventos tiene la siguiente estructura:

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

Reglas de unión y semántica

Al unir datos de referencia, siga las siguientes restricciones:

La comparación de nombres de clave distingue mayúsculas de minúsculas.
La comparación de valores clave distingue mayúsculas de minúsculas para las propiedades de cadena.

Para entornos con más de un conjunto de datos de referencia, se aplican tres restricciones adicionales durante las combinaciones:

Cada elemento de un conjunto de datos de referencia puede especificar su propia lista de propiedades que no son clave.
Para los dos conjuntos de datos de referencia A y B, las propiedades que no son de clave no deben intersecarse.
Los conjuntos de datos de referencia solo se unen directamente a eventos, nunca a otros conjuntos de datos a los que se hace referencia (y, a continuación, a eventos). Para unir un elemento de datos de referencia a un evento, todas las propiedades clave que se usan en el elemento de datos de referencia deben estar presentes en el evento . Además, las propiedades de clave no deben provenir de las propiedades que no son clave unidas a un evento a través de algún otro elemento de datos de referencia.

Dadas estas restricciones, el motor de combinación puede aplicar la combinación en cualquier orden para un evento determinado. No se tienen en cuenta la jerarquía ni la ordenación.

Límites actuales

Puede agregar hasta dos conjuntos de datos de referencia por entorno de Azure Time Series Insights Gen1. En la tabla siguiente se muestran limitaciones adicionales asociadas a los datos de referencia de Azure Time Series Insights Gen1:

Nombre del límite	Valor límite	SKU afectadas	Notas
Recuento de propiedades de clave	3	S1, S2	Por conjunto de datos de referencia; Azure Resource Manager y solo el Azure Portal
Tamaño de propiedad de clave	1 KB	S1, S2	Conjunto de datos por referencia
Recuento de elementos de datos de referencia	2.000/20.000 (S1/S2)	S1, S2	Por unidad; por ejemplo, 4 unidades SKU S1 = 8000 elementos (4 x 2000)
Número máximo de transacciones simultáneas	10/2/10 (S1/S2)	S1, S2
Número máximo de transacciones de datos de referencia	120/600 (S1/S2)	S1, S2	Por hora
Número máximo de elementos de datos de referencia	1,000	S1, S2	Por transacción
Tamaño máximo del elemento de datos de referencia	8 192 KB	S1, S2	Por transacción

Consulte también

Para más información sobre el registro de aplicaciones y el modelo de programación de Azure Active Directory, consulte Azure Active Directory para desarrolladores.

Para obtener información sobre los parámetros de solicitud y autenticación, consulte Autenticación y autorización.

Entre las herramientas que ayudan a probar las solicitudes y respuestas HTTP se incluyen las siguientes:

Fiddler. Este proxy de depuración web gratuito puede interceptar las solicitudes REST, por lo que puede diagnosticar los mensajes de solicitud y respuesta HTTP.
JWT.io. Puede usar esta herramienta para volcar rápidamente las notificaciones en el token de portador y, a continuación, validar su contenido.
Postman. Se trata de una herramienta gratuita de prueba de solicitudes y respuestas HTTP para depurar las API REST.

Para más información sobre Azure Time Series Insights Gen1, revise la documentación de Gen1.

Compartir a través de

API de datos de referencia de Azure Time Series Insights Gen1

Introducción a la API

Colocar elementos de datos de referencia

Revisión de los elementos de datos de referencia

Eliminar propiedades en elementos de datos de referencia

Eliminar elementos de datos de referencia

Obtener elementos de datos de referencia

Validación y control de errores

Códigos de error de elemento

Ejemplo de combinación de datos de referencia

Reglas de unión y semántica

Límites actuales

Consulte también

Recursos adicionales