Použití rozhraní IoT Central REST API ke správě organizací

Článek
10/27/2023

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. Rozhraní REST API můžete použít ke správě organizací v aplikaci IoT Central.

Každé volání rozhraní REST API služby IoT Central vyžaduje autorizační hlavičku. Další informace najdete v tématu Ověřování a autorizace volání rozhraní REST API služby IoT Central.

Referenční dokumentaci k rozhraní IoT Central REST API najdete v referenčních informacích k rozhraní REST API služby Azure IoT Central.

Další informace o organizacích v aplikaci IoT Central najdete v tématu Správa organizací IoT Central.

Tip

Pomocí nástroje Postman můžete vyzkoušet volání rozhraní REST API popsaná v tomto článku. Stáhněte si kolekci IoT Central Postman a naimportujte ji do Postmanu. V kolekci budete muset nastavit proměnné, jako je subdoména vaší aplikace a token správce.

Rozhraní REST API organizací

Rozhraní IoT Central REST API umožňuje:

Přidání organizace do aplikace
Získání organizace podle ID
Aktualizace organizace v aplikaci
Získání seznamu organizací v aplikaci
Odstranění organizace v aplikaci

Vytváření organizací

Rozhraní REST API umožňuje vytvářet organizace v aplikaci IoT Central. K vytvoření organizace ve vaší aplikaci použijte následující požadavek:

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

organizationId – jedinečné ID organizace

Následující příklad ukazuje text požadavku, který přidá organizaci do aplikace IoT Central.

{
  "displayName": "Seattle",
}

Text požadavku obsahuje některá povinná pole:

@displayName: Zobrazovaný název organizace.

Text požadavku obsahuje některá volitelná pole:

@parent: ID nadřazené organizace.

Pokud nezadáte nadřazený objekt, organizace získá výchozí organizaci nejvyšší úrovně jako nadřazenou.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Můžete vytvořit organizaci s hierarchií, například vytvořit prodejní organizaci s nadřazenou organizací.

Následující příklad ukazuje text požadavku, který přidá organizaci do aplikace IoT Central.

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Získání organizace

Pomocí následujícího požadavku načtěte podrobnosti o jednotlivých organizacích z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Aktualizace organizace

Pomocí následujícího požadavku aktualizujte podrobnosti o organizaci ve vaší aplikaci:

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

Následující příklad ukazuje text požadavku, který aktualizuje nadřazenou položku organizace:

{
  "parent": "washington"
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Seznam organizací

Pomocí následujícího požadavku načtěte seznam organizací z vaší aplikace:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu.

{
    "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"
        }
    ]
}

Organizace Washington, Redmond a Bellevue automaticky mají výchozí organizaci nejvyšší úrovně aplikace jako nadřazenou.

Odstranění organizace

K odstranění organizace použijte následující požadavek:

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

Použití organizací

Pomocí organizací můžete spravovat přístup k prostředkům ve vaší aplikaci.

Správa rolí

Rozhraní REST API umožňuje vypsat role definované v aplikaci IoT Central. Pomocí následujícího požadavku načtěte ze své aplikace seznam ID rolí aplikací a rolí organizace. Další informace najdete v tématu Správa organizací IoT Central:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu, který obsahuje ID rolí aplikace a rolí organizace.

{
    "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"
        }
    ]
}

Vytvoření tokenu rozhraní API připojeného k uzlu v hierarchii organizace

Pomocí následujícího požadavku vytvořte v aplikaci token rozhraní API připojený k uzlu v hierarchii organizace:

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

tokenId – jedinečné ID tokenu

Následující příklad ukazuje text požadavku, který vytvoří token rozhraní API pro organizaci Seattle v aplikaci IoT Central.

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

Text požadavku obsahuje některá povinná pole:

Název	Popis
role	ID jedné z rolí organizace
organization	ID organizace

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

{
    "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"
}

Přidružení uživatele k uzlu v hierarchii organizace

Pomocí následujícího požadavku vytvořte a přidružte uživatele k uzlu v hierarchii organizace ve vaší aplikaci. ID a e-mail musí být v aplikaci jedinečné:

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

V následujícím textu role požadavku je ID jedné z rolí organizace a organization ID organizace.

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

}

Odpověď na tento požadavek vypadá jako v následujícím příkladu. Hodnota role určuje, ke které roli je uživatel přidružený:

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

Přidání a přidružení zařízení k organizaci

Pomocí následujícího požadavku přidružte nové zařízení k organizaci.

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

Následující příklad ukazuje text požadavku, který přidá zařízení pro šablonu zařízení. Podrobnosti najdete template na stránce šablon zařízení v uživatelském rozhraní aplikace IoT Central.

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

Text požadavku obsahuje některá povinná pole:

@displayName: Zobrazovaný název zařízení.
@enabled: deklaruje, že tento objekt je rozhraní.
@etag: ETag použitý k zabránění konfliktům v aktualizacích zařízení.
simulated: Simuluje se zařízení?
template : Definice šablony zařízení pro zařízení.
organizations : Seznam ID organizace, na které je zařízení součástí. V současné době můžete zařízení přidružit jenom k jedné organizaci.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

}

Přidání a přidružení skupiny zařízení k organizaci

Pomocí následujícího požadavku vytvořte a přidružte novou skupinu zařízení k organizaci.

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

Když vytvoříte skupinu zařízení, definujete filter , která vybere zařízení, která se mají do skupiny přidat. A filter identifikuje šablonu zařízení a všechny vlastnosti, které se mají shodovat. Následující příklad vytvoří skupinu zařízení, která obsahuje všechna zařízení přidružená k dtmi:modelDefinition:dtdlv2 šabloně, ve které provisioned je vlastnost true.

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

Text požadavku obsahuje některá povinná pole:

@displayName: Zobrazovaný název skupiny zařízení.
@filter: Dotaz definující zařízení, která mají být v této skupině.
description: Krátký přehled skupiny zařízení.
organizations : Seznam ID organizace, na které je zařízení součástí. V současné době můžete zařízení přidružit jenom k jedné organizaci.

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Další kroky

Teď, když jste se naučili spravovat organizace pomocí rozhraní REST API, je navrhovaným dalším krokem použití rozhraní IoT Central REST API ke správě exportů dat.

Použití rozhraní IoT Central REST API ke správě organizací

Rozhraní REST API organizací

Vytváření organizací

Získání organizace

Aktualizace organizace

Seznam organizací

Odstranění organizace

Použití organizací

Správa rolí

Vytvoření tokenu rozhraní API připojeného k uzlu v hierarchii organizace

Přidružení uživatele k uzlu v hierarchii organizace

Přidání a přidružení zařízení k organizaci

Přidání a přidružení skupiny zařízení k organizaci

Další kroky

Další materiály