Verwenden der IoT Central-REST-API zum Verwalten von Benutzern und Rollen

Artikel
10/22/2024

Mit der IoT Central-REST-API können Sie Clientanwendungen entwickeln, die in IoT Central-Anwendungen integriert werden. Sie können mit der REST-API auch Benutzer und Rollen in Ihrer IoT Central-Anwendung verwalten.

Jeder IoT Central-REST-API-Aufruf erfordert einen Autorisierungsheader. Weitere Informationen finden Sie unter Authentifizieren und Autorisieren von IoT Central-REST-API-Aufrufen.

Hinweis

Vorgänge für Benutzer und Rollen werden im Überwachungsprotokoll des IoT Central aufgezeichnet.

Die Referenzdokumentation für die IoT Central-REST-API finden Sie unter Azure IoT Central: Referenz zur REST-API.

Informationen zum Verwalten von Benutzern und Rollen mithilfe der IoT Central-Benutzeroberfläche finden Sie unter Verwalten von Benutzern und Rollen in Ihrer IoT Central-Anwendung.

Rollen verwalten

Mit der REST-API können Sie die in Ihrer IoT Central-Anwendung definierten Rollen auflisten. Verwenden Sie die folgende Anforderung zum Abrufen einer Liste von Rollen-IDs aus Ihrer Anwendung:

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

Die Antwort auf diese Anforderung sieht wie im folgenden Beispiel aus, das die drei integrierten Rollen und eine benutzerdefinierte Rolle enthält:

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

Hinweis

Dieser Befehl zeigt nur Rollen an, die einer Anwendung und nicht einer benutzerdefinierten Rolle auf Organisationsebene zugeordnet sind.

Verwalten von Benutzern

Mit der REST-API können Sie Folgendes durchführen:

Auflisten der Benutzer in einer Anwendung
Abrufen der Details zu einem einzelnen Benutzer
Erstellen eines Benutzers
Ändern eines Benutzers
Löschen eines Benutzers

Auflisten von Benutzern

Verwenden Sie die folgende Anforderung zum Abrufen einer Liste von Benutzern aus Ihrer Anwendung:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus. Die Rollenwerte geben die Rollen-ID an, der der Benutzer zugeordnet ist:

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

Abrufen eines Benutzers

Verwenden Sie die folgende Anforderung zum Abrufen von Details zu einem einzelnen Benutzer aus Ihrer Anwendung:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus. Der Rollenwert gibt die Rollen-ID an, der der Benutzer zugeordnet ist:

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

Erstellen eines Benutzers

Verwenden Sie die folgende Anforderung zum Erstellen eines Benutzers in Ihrer Anwendung. Die ID und E-Mail-Adresse müssen in der Anwendung eindeutig sein:

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

Im folgenden Anforderungstext steht der role Wert für die Operatorrolle, die Sie zuvor abgerufen haben:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus. Der Rollenwert gibt die Rolle an, der der Benutzer zugeordnet ist:

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

Sie können auch einen Dienstprinzipalbenutzer hinzufügen. Dies ist hilfreich, wenn Sie die Dienstprinzipalauthentifizierung für REST-API-Aufrufe verwenden müssen. Weitere Informationen finden Sie unter Hinzufügen oder Erstellen eines Dienstprinzipalbenutzers.

Ändern der Rolle eines Benutzers

Verwenden Sie die folgende Anforderung zum Ändern der einem Benutzer zugewiesenen Rolle. In diesem Beispiel wird die ID der Generatorrolle verwendet, die Sie zuvor abgerufen haben:

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

Anforderungstext. Der Wert gilt für die Generatorrolle, die Sie zuvor abgerufen haben:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Löschen eines Benutzers

Verwenden Sie die folgende Anforderung zum Löschen eines Benutzers:

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

Nächste Schritte

Nachdem Sie erfahren haben, wie Benutzer und Rollen über die REST-API verwaltet werden, empfiehlt sich als nächster Schritt das Verwenden der IoT Central-REST-API zum Verwalten von Organisationen.

Teilen über