Správa uživatelů a rolí s využitím rozhraní IoT Central REST API

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ě uživatelů a rolí 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.

Poznámka:

Operace s uživateli a rolemi se zaznamenávají v protokolu auditu 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.

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.

Informace o správě uživatelů a rolí pomocí uživatelského rozhraní IoT Central najdete v tématu Správa uživatelů a rolí v aplikaci IoT Central.

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í:

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 tři předdefinované role a vlastní roli:

{
  "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": "16f8533f-6b82-478f-8ba8-7e676b541b1b",
      "displayName": "Example custom role"
    }
  ]
}

Poznámka:

Tento příkaz zobrazuje jenom role přidružené k aplikaci, nikoli vlastní roli na úrovni organizace.

Spravovat uživatele

Rozhraní REST API umožňuje:

• Zobrazení seznamu uživatelů v aplikaci
• Načtení podrobností o jednotlivých uživatelích
• Vytvoření uživatele
• Úprava uživatele
• Odstranění uživatele

Vypsání uživatelů

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

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

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

{
  "value": [
    {
      "id": "91907508-04fe-4349-91b5-b872f3055a95",
      "type": "email",
      "roles": [
        {
          "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
        }
      ],
      "email": "user1@contoso.com"
    },
    {
      "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
      "type": "email",
      "roles": [
        {
          "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
        }
      ],
      "email": "user2@contoso.com"
    },
    {
      "id": "3ab9375e-d2d9-42da-b419-6ae86a938321",
      "type": "email",
      "roles": [
        {
          "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
        }
      ],
      "email": "user3@contoso.com"
    },
    {
      "id": "fc5a250b-83fb-433d-892c-e0a144f68c2b",
      "type": "email",
      "roles": [
        {
          "role": "16f8533f-6b82-478f-8ba8-7e676b541b1b"
        }
      ],
      "email": "user4@contoso.com"
    }
  ]
}

Získání uživatele

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

GET https://{your app subdomain}.azureiotcentral.com/api/users/dc1c916b-a652-49ea-b128-7c465a54c759?api-version=2022-07-31

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

{
  "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user2@contoso.com"
}

Vytvoření uživatele

Pomocí následujícího požadavku vytvořte uživatele 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 požadavku je hodnota pro roli operátora, role kterou jste získali dříve:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "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": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user5@contoso.com"
}

Můžete také přidat uživatele instančního objektu, který je užitečný v případě, že potřebujete použít ověřování instančního objektu pro volání rozhraní REST API. Další informace najdete v tématu Přidání nebo aktualizace uživatele instančního objektu.

Změna role uživatele

Pomocí následujícího požadavku můžete změnit roli přiřazenou uživateli. V tomto příkladu se používá ID role tvůrce, kterou jste získali dříve:

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

Text požadavku. Hodnota je pro roli tvůrce, kterou jste získali dříve:

{
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

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

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ],
  "email": "user5@contoso.com"
}

Odstranění uživatele

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

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

Další kroky

Teď, když jste se naučili spravovat uživatele a role pomocí rozhraní REST API, je navrhovaným dalším krokem postup, jak používat rozhraní IoT Central REST API ke správě organizací.