Cómo consultar las API de Azure Digital Twins para tareas comunes

Artículo
02/24/2020

Importante

Se ha publicado una nueva versión del servicio Azure Digital Twins. A la luz de las funcionalidades ampliadas del nuevo servicio, se ha retirado el servicio Azure Digital Twins original (descrito en este conjunto de documentación).

Para ver la documentación del nuevo servicio, visite la documentación activa de Azure Digital Twins.

En este artículo se muestran los patrones de consulta que le ayudan a ejecutar escenarios comunes para la instancia de Azure Digital Twins. Se da por hecho que su instancia de Digital Twins ya está en ejecución. Puede usar a cualquier cliente de REST, como Postman.

En los ejemplos siguientes, YOUR_MANAGEMENT_API_URL hace referencia al identificador URI de la API de Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Nombre	Reemplazar por
YOUR_INSTANCE_NAME	El nombre de la instancia de Azure Digital Twins
YOUR_LOCATION	La región en la que está hospedada la instancia

Consultas de espacios y tipos

En esta sección se muestran consultas de ejemplo para obtener más información sobre los espacios aprovisionados. Realice solicitudes HTTP GET autenticadas con las consultas de ejemplo, y reemplace los marcadores de posición por valores de su configuración.

Obtenga espacios que son nodos raíz.

YOUR_MANAGEMENT_API_URL/spaces?$filter=ParentSpaceId eq null

Obtenga un espacio por su nombre e incluya dispositivos, sensores, valores calculados y valores de sensor.

YOUR_MANAGEMENT_API_URL/spaces?name=Focus Room A1&includes=fullpath,devices,sensors,values,sensorsvalues

Obtenga espacios y su información de dispositivo/sensor, cuyo elemento principal es el identificador de espacio especificado, y que se encuentran en los niveles del dos al cinco en relación con el espacio especificado.
```
YOUR_MANAGEMENT_API_URL/spaces?spaceId=YOUR_SPACE_ID&includes=fullpath,devices,sensors,values,sensorsvalues&traverse=Down&minLevel=1&minRelative=true&maxLevel=5&maxRelative=true
```

Obtenga el espacio con el identificador dado e incluya valores de sensor y calculados.

YOUR_MANAGEMENT_API_URL/spaces?ids=YOUR_SPACE_ID&includes=Values,sensors,SensorsValues

Obtenga las claves de propiedad de un determinado espacio.

YOUR_MANAGEMENT_API_URL/propertykeys?spaceId=YOUR_SPACE_ID

Obtenga espacios con la clave de propiedad denominada AreaInSqMeters y cuyo valor sea 30. También puede realizar operaciones de cadena, por ejemplo, obtener espacios que contengan la clave de propiedad con name = X contains Y.
```
YOUR_MANAGEMENT_API_URL/spaces?propertyKey=AreaInSqMeters&propertyValue=30
```

Obtenga todos los nombres con el nombre Temperature y las dependencias y ontologías asociadas.

YOUR_MANAGEMENT_API_URL/types?names=Temperature&includes=space,ontologies,description,fullpath

Consulta de roles y asignaciones de roles

En esta sección se muestran algunas consultas para obtener más información sobre los roles y sus asignaciones.

Obtenga todos los roles compatibles con Azure Digital Twins.
```
YOUR_MANAGEMENT_API_URL/system/roles
```
Obtenga todas las asignaciones de roles de su instancia de Digital Twins.
```
YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=down
```
Obtenga las asignaciones de roles en una ruta de acceso determinada.
```
YOUR_MANAGEMENT_API_URL/roleassignments?path=/A_SPATIAL_PATH
```

Consultas de dispositivos

En esta sección se muestran algunos ejemplos de cómo puede usar las API de administración para obtener información específica sobre sus dispositivos. Todas las llamadas de API deben ser solicitudes HTTP GET autenticadas.

Obtenga todos los dispositivos.
```
YOUR_MANAGEMENT_API_URL/devices
```

Busque todos los estados de dispositivo.

YOUR_MANAGEMENT_API_URL/system/devices/statuses

Obtenga un dispositivo específico.

YOUR_MANAGEMENT_API_URL/devices/YOUR_DEVICE_ID

Obtenga todos los dispositivos asociados al espacio raíz.
```
YOUR_MANAGEMENT_API_URL/devices?maxLevel=1
```
Obtenga todos los dispositivos asociados a espacios en los niveles de 2 a 4.
```
YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4
```
Obtenga todos los dispositivos asociados directamente a un identificador de espacio determinado.
```
YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID
```
Obtenga todos los dispositivos asociados a un espacio concreto y sus descendientes.
```
YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down
```

Obtenga todos los dispositivos asociados a los descendientes de un espacio, excepto ese espacio.

YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down&minLevel=1&minRelative=true

Obtenga todos los dispositivos asociados a elementos secundarios directos de un espacio.

YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true

Obtenga todos los dispositivos asociados a uno de los antecesores de un espacio.

YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Up&maxLevel=-1&maxRelative=true

Obtenga todos los dispositivos asociados a los descendientes de un espacio que sean de nivel inferior o igual a 5.
```
YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Down&maxLevel=5
```
Obtenga todos los dispositivos asociados a espacios que se encuentran en el mismo nivel que el espacio con el identificador YOUR_SPACE_ID.
```
YOUR_MANAGEMENT_API_URL/devices?spaceId=YOUR_SPACE_ID&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true
```
Obtenga la cadena de conexión de dispositivos de IoT Hub para su dispositivo.
```
YOUR_MANAGEMENT_API_URL/devices/YOUR_DEVICE_ID?includes=ConnectionString
```
Obtenga el dispositivo con el identificador de hardware dado, incluidos los sensores asociados.
```
YOUR_MANAGEMENT_API_URL/devices?hardwareIds=YOUR_DEVICE_HARDWARE_ID&includes=sensors
```
Obtenga los sensores de tipos de datos determinados, en este caso Motion y Temperature.
```
YOUR_MANAGEMENT_API_URL/sensors?dataTypes=Motion,Temperature
```

Consultas de buscadores de coincidencias y funciones definidas por el usuario

Obtenga todos los buscadores de coincidencias aprovisionados y sus identificadores.
```
  YOUR_MANAGEMENT_API_URL/matchers
```
Obtenga detalles sobre un buscador de coincidencias determinado, incluidos los espacios y la función definida por el usuario asociada a él.
```
YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_ID?includes=description, conditions, fullpath, userdefinedfunctions, space
```
Evalúe un buscador de coincidencias con un sensor y habilite el registro con fines de depuración. La devolución de este mensaje GET HTTP indica si el buscador de coincidencias y el sensor pertenecen al tipo de datos.
```
  YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_ID/evaluate/YOUR_SENSOR_ID?enableLogging=true
```
Obtenga el identificador de las funciones definidas por el usuario.
```
  YOUR_MANAGEMENT_API_URL/userdefinedfunctions
```

Obtenga el contenido de una determinada función definida por el usuario.

  YOUR_MANAGEMENT_API_URL/userdefinedfunctions/YOUR_USER_DEFINED_FUNCTION_ID/contents

Consultas de usuarios

En esta sección se muestran algunas consultas de API de ejemplo para administrar usuarios en Azure Digital Twins. Realice una solicitud GET HTTP y reemplace los marcadores de posición por valores de su configuración.

Obtenga todos los usuarios.
```
YOUR_MANAGEMENT_API_URL/users
```

Obtenga un usuario específico.

YOUR_MANAGEMENT_API_URL/users/ANY_USER_ID

Pasos siguientes

Para aprender cómo autenticar con la API de administración, lea Autenticación con las API.

Para más información sobre los puntos de conexión de API, lea Uso de Digital Twins Swagger.

Compartir a través de