Comparteix a través de

Cómo utilizar la API REST de IoT Central para administrar organizaciones

  • Article

La API de REST de IoT Central permite desarrollar aplicaciones cliente que se integran con aplicaciones de IoT Central. Puede usar la API REST para administrar organizaciones en la aplicación de IoT Central.

Cada llamada a la API REST de IoT Central requiere un encabezado de autorización. Para obtener más información, vea los procedimientos de autenticación y autorización de llamadas a la API REST de IoT Central.

Para ver la documentación de referencia sobre la API REST de IoT Central, consulte Referencia de la API REST de Azure IoT Central.

Para más información sobre las organizaciones en la aplicación IoT Central, consulte Administración de organizaciones de IoT Central.

API REST de organizaciones

La API de REST de IoT Central le permite:

  • Adición de una organización a la aplicación
  • Obtención de una organización por identificador
  • Actualización de una organización en la aplicación
  • Obtención de una lista de las organizaciones en la aplicación
  • Eliminación de una organización en la aplicación

Creación de organizaciones

La API REST le permite crear organizaciones en su aplicación IoT Central. Use la siguiente solicitud para crear una organización en la aplicación:

PUT https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31
  • organizationId: identificador único de la organización

En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega una organización a una aplicación IoT Central.

{
  "displayName": "Seattle",
}

El cuerpo de la solicitud tiene algunos campos obligatorios:

  • @displayName: nombre para mostrar de la organización.

El cuerpo de la solicitud tiene algunos campos opcionales:

  • @parent: identificador del elemento primario de la organización.

Si no especifica un elemento primario, la organización obtiene la organización de nivel superior predeterminada como su elemento primario.

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "id": "seattle",
  "displayName": "Seattle"
}

Puede crear una organización con jerarquía, por ejemplo, puede crear una organización de ventas con una organización primaria.

En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega una organización a una aplicación IoT Central.

{
  "displayName": "Sales",
  "parent":"seattle"
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "id": "sales",
  "displayName": "Sales",
  "parent":"Seattle"
}

Obtención de una organización

Use la siguiente solicitud para recuperar los detalles de una organización individual desde la aplicación:

GET https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "id": "seattle",
  "displayName": "Seattle",
  "parent": "washington"
}

Actualizar una organización

Use la siguiente solicitud para actualizar los detalles de una organización en la aplicación:

PATCH https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

En el ejemplo siguiente se muestra un cuerpo de solicitud que actualiza el elemento principal de la organización:

{
  "parent": "washington"
}

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "id": "seattle",
  "displayName": "Seattle Sales",
  "parent": "washington"
}

Enumeración de organizaciones

Use la siguiente solicitud para recuperar una lista de organizaciones de la aplicación:

GET https://{your app subdomain}.azureiotcentral.com/api/organizations?api-version=2022-07-31

La respuesta a esta solicitud es similar al ejemplo siguiente.

{
    "value": [
        {
            "id": "washington",
            "displayName": "Washington"
        },
        {
            "id": "redmond",
            "displayName": "Redmond"
        },
        {
            "id": "bellevue",
            "displayName": "Bellevue"
        },
        {
            "id": "spokane",
            "displayName": "Spokane",
            "parent": "washington"
        },
        {
            "id": "seattle",
            "displayName": "Seattle",
            "parent": "washington"
        }
    ]
}

Las organizaciones Washington, Redmond y Bellevue tienen automáticamente la organización de nivel superior predeterminada de la aplicación como principal.

Eliminación de una organización

Use la siguiente solicitud para eliminar una organización:

DELETE https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

Uso de organizaciones

Use organizaciones para administrar el acceso a los recursos de la aplicación.

Administrar roles

La API REST permite enumerar los roles definidos en su aplicación de IoT Central. Utilice la siguiente solicitud para recuperar una lista de identificadores de roles de aplicación y roles de organización de su aplicación. Para obtener más información, consulte Administración de organizaciones de IoT Central:

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

La respuesta a esta solicitud es similar al siguiente ejemplo, que incluye los identificadores de los roles de aplicación y de organización.

{
    "value": [
        {
            "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
            "displayName": "Administrator"
        },
        {
            "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
            "displayName": "Operator"
        },
        {
            "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
            "displayName": "Builder"
        },
        {
            "id": "c495eb57-eb18-489e-9802-62c474e5645c",
            "displayName": "Org Admin"
        },
        {
            "id": "b4935647-30e4-4ed3-9074-dcac66c2f8ef",
            "displayName": "Org Operator"
        },
        {
            "id": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "displayName": "Org Viewer"
        }
    ]
}

Creación de un token de API asociado a un nodo de la jerarquía de una organización

Use la siguiente solicitud para crear un token de API asociado a un nodo de la jerarquía de una organización en su aplicación:

PUT https://{your app subdomain}.azureiotcentral.com/api/apiTokens/{tokenId}?api-version=2022-07-31
  • tokenId: identificador único del token.

El ejemplo siguiente muestra el cuerpo de una solicitud que crea un token de API para la organización seattle en una aplicación de IoT Central.

{
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ]
}

El cuerpo de la solicitud tiene algunos campos obligatorios:

Nombre Descripción
rol Identificador de uno de los roles de la organización
organization Id. de la organización.

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "id": "token1",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "expiry": "2023-07-07T17:05:08.407Z",
    "token": "SharedAccessSignature sr=8a0617**********************4c0d71c&sig=3RyX69G4%2FBZZnG0LXOjQv*************e8s%3D&skn=token1&se=1688749508407"
}

Asociación de un usuario a un nodo de la jerarquía de una organización

Use la siguiente solicitud para crear y asociar un usuario a un nodo de la jerarquía de una organización en su aplicación. El identificador y el correo electrónico deben ser únicos en la aplicación:

PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

En el siguiente cuerpo de solicitud, role es el identificador de uno de los roles de organización y organization es el identificador de la organización.

{
  "id": "user-001",
  "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"

}

La respuesta a esta solicitud es similar al ejemplo siguiente. El valor de rol indica el rol al que está asociado el usuario:

{
    "id": "user-001",
    "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"
}

Adición y asociación de un dispositivo a una organización

Use la siguiente solicitud para asociar un nuevo dispositivo a una organización.

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}?api-version=2022-07-31

En el ejemplo siguiente se muestra un cuerpo de solicitud que agrega un dispositivo para una plantilla de dispositivo. Puede obtener los detalles de template en la página de plantillas de dispositivo de la interfaz de usuario de la aplicación de IoT Central.

{
    "displayName": "CheckoutThermostat",
    "template": "dtmi:contoso:Thermostat;1",
    "simulated": true,
    "enabled": true,
    "organizations": [
        "seattle"
    ]
}

El cuerpo de la solicitud tiene algunos campos obligatorios:

  • @displayName: nombre para mostrar del dispositivo.
  • @enabled: declara que este objeto es una interfaz.
  • @etag: ETag se usa para evitar conflictos en las actualizaciones del dispositivo.
  • simulated: ¿el dispositivo está simulado?
  • template: la definición de plantilla de dispositivo para el dispositivo.
  • organizations: lista de los identificadores de organización de los que forma parte el dispositivo. Actualmente, un dispositivo se puede asociar únicamente a una organización.

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true,
   "organizations": [
    "seattle"
  ]

}

Adición y asociación de un grupo de dispositivos a una organización

Use la siguiente solicitud para crear y asociar un nuevo grupo de dispositivos a una organización.

PUT https://{your app subdomain}.azureiotcentral.com/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Al crear un grupo de dispositivos, se define un objeto filter que selecciona los dispositivos que se van a agregar al grupo. Un elemento filter identifica una plantilla de dispositivo y cualquier propiedad que coincida. En el ejemplo siguiente, se crea un grupo de dispositivos que contiene todos los dispositivos asociados a la plantilla dtmi:modelDefinition:dtdlv2, donde la propiedad provisioned es "true".

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

El cuerpo de la solicitud tiene algunos campos obligatorios:

  • @displayName: nombre para mostrar del grupo de dispositivos.
  • @filter: consulta que define qué dispositivos deben estar en este grupo.
  • description: breve resumen del grupo de dispositivos.
  • organizations: lista de los identificadores de organización de los que forma parte el dispositivo. Actualmente, un dispositivo se puede asociar únicamente a una organización.

La respuesta a esta solicitud es similar al ejemplo siguiente:

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Pasos siguientes

Ahora que ha aprendido a administrar organizaciones con la API REST, el siguiente paso que se sugiere es Uso de la API REST de IoT Central para administrar las exportaciones de datos.