Jak zarządzać użytkownikami i rolami za pomocą interfejsu API REST usługi IoT Central

Artykuł
02/14/2024

Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich, które integrują się z aplikacjami usługi IoT Central. Interfejs API REST umożliwia zarządzanie użytkownikami i rolami w aplikacji usługi IoT Central.

Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji. Aby dowiedzieć się więcej, zobacz Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central.

Uwaga

Operacje na użytkownikach i rolach są rejestrowane w dzienniku inspekcji usługi IoT Central.

Aby uzyskać dokumentację referencyjną interfejsu API REST usługi IoT Central, zobacz Dokumentacja interfejsu API REST usługi Azure IoT Central.

Napiwek

Narzędzie Postman umożliwia wypróbowanie wywołań interfejsu API REST opisanych w tym artykule. Pobierz kolekcję IoT Central Postman i zaimportuj ją do narzędzia Postman. W kolekcji należy ustawić zmienne, takie jak poddomena aplikacji i token administratora.

Aby dowiedzieć się, jak zarządzać użytkownikami i rolami przy użyciu interfejsu użytkownika usługi IoT Central, zobacz Zarządzanie użytkownikami i rolami w aplikacji usługi IoT Central.

Zarządzanie rolami

Interfejs API REST umożliwia wyświetlenie listy ról zdefiniowanych w aplikacji usługi IoT Central. Użyj następującego żądania, aby pobrać listę identyfikatorów ról z aplikacji:

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

Odpowiedź na to żądanie wygląda podobnie do następującego przykładu, który zawiera trzy wbudowane role i rolę niestandardową:

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

Uwaga

To polecenie pokazuje tylko role skojarzone z aplikacją, a nie niestandardową rolę na poziomie organizacji.

Zarządzaj użytkownikami

Interfejs API REST umożliwia:

Wyświetlanie listy użytkowników w aplikacji
Pobieranie szczegółów pojedynczego użytkownika
Tworzenie użytkownika
Modyfikowanie użytkownika
Usuwanie użytkownika

Wyświetlanie użytkowników

Użyj następującego żądania, aby pobrać listę użytkowników z aplikacji:

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

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu. Wartości roli identyfikują identyfikator roli, z jaką użytkownik jest skojarzony:

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

Pobieranie użytkownika

Użyj następującego żądania, aby pobrać szczegóły poszczególnych użytkowników z aplikacji:

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

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu. Wartość roli identyfikuje identyfikator roli skojarzony z użytkownikiem:

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

Tworzenie użytkownika

Użyj następującego żądania, aby utworzyć użytkownika w aplikacji. Identyfikator i adres e-mail muszą być unikatowe w aplikacji:

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

W następującej treści role żądania wartość jest dla roli operatora pobranej wcześniej:

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

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu. Wartość roli określa, z którą rolą jest skojarzony użytkownik:

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

Możesz również dodać użytkownika jednostki usługi, który jest przydatny, jeśli musisz użyć uwierzytelniania jednostki usługi na potrzeby wywołań interfejsu API REST. Aby dowiedzieć się więcej, zobacz Dodawanie lub aktualizowanie użytkownika jednostki usługi.

Zmienianie roli użytkownika

Użyj następującego żądania, aby zmienić rolę przypisaną do użytkownika. W tym przykładzie użyto identyfikatora pobranej wcześniej roli konstruktora:

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

Treść żądania. Wartość jest dla roli konstruktora pobranej wcześniej:

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

Odpowiedź na to żądanie wygląda następująco:

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

Usuwanie użytkownika

Użyj następującego żądania, aby usunąć użytkownika:

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

Następne kroki

Teraz, gdy wiesz już, jak zarządzać użytkownikami i rolami za pomocą interfejsu API REST, sugerowanym następnym krokiem jest jak używać interfejsu API REST usługi IoT Central do zarządzania organizacjami.

Udostępnij za pośrednictwem