Freigeben über

Verwenden der IoT Central REST-API zum Verwalten von Organisationen

  • Artikel

Mit der IoT Central-REST-API können Sie Clientanwendungen entwickeln, die in IoT Central-Anwendungen integriert werden. Sie können die REST-API verwenden, um Organisationen in Ihrer IoT Central-Anwendung zu verwalten.

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

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

Weitere Informationen zu Organisationen in der IoT Central Anwendung finden Sie unter Verwalten von IoT Central-Organisationen.

Organisations-REST-API

Mit der IoT Central-REST-API können Sie folgende Aktionen ausführen:

  • Hinzufügen einer Organisation zu Ihrer Anwendung
  • Abrufen einer Organisation nach ID
  • Aktualisieren einer Organisation in Ihrer Anwendung
  • Abrufen einer Liste der Organisationen in der Anwendung
  • Löschen einer Organisation in Ihrer Anwendung

Erstellen von Organisationen

Mit der REST-API können Sie Organisationen in Ihrer IoT Central-Anwendung erstellen. Verwenden Sie die folgende Anforderung zum Erstellen einer Organisation in Ihrer Anwendung:

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

Das folgende Beispiel zeigt einen Anforderungstext, mit dem einer IoT Central-Anwendung eine Organisation hinzufügt wird.

{
  "displayName": "Seattle",
}

Der Anforderungstext enthält einige erforderliche Felder:

  • @displayName: Anzeigename der Organisation.

Der Anforderungstext enthält einige optionale Felder:

  • @parent: ID des übergeordneten Elements der Organisation.

Wenn Sie kein übergeordnetes Element angeben, erhält die Organisation standardmäßig die Organisation auf obersten Ebene als übergeordnetes Element.

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

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

Sie können eine Organisation mit Hierarchie erstellen, z. B. eine Vertriebsorganisation mit einer übergeordneten Organisation.

Das folgende Beispiel zeigt einen Anforderungstext, mit dem einer IoT Central-Anwendung eine Organisation hinzufügt wird.

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

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

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

Abrufen einer Organisation

Verwenden Sie die folgende Anforderung zum Abrufen von Details zu einer einzelnen Organisation aus Ihrer Anwendung:

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

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

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

Organisation aktualisieren

Verwenden Sie die folgende Anforderung zum Aktualisieren einer Organisation in Ihrer Anwendung:

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

Das folgende Beispiel zeigt eine Anforderung, die das übergeordnete Element der Organisation aktualisiert:

{
  "parent": "washington"
}

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

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

Auflisten von Organisationen

Verwenden Sie die folgende Anforderung, um eine Liste der Organisationen aus Ihrer Anwendung abzurufen:

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

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

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

Die Organisationen Washington, Redmond und Bellevue haben als übergeordnetes Element automatisch die Standardorganisation auf der obersten Ebene der Anwendung.

Organisation löschen

Verwenden Sie die folgende Anforderung, um eine Organisation zu löschen:

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

Verwenden von Organisationen

Verwenden Sie Organisationen, um den Zugriff auf Ressourcen in Ihrer Anwendung zu verwalten.

Rollen verwalten

Mit der REST-API können Sie die in Ihrer IoT Central-Anwendung definierten Rollen auflisten. Rufen Sie mithilfe der folgenden Anforderung eine Liste der IDs von Anwendungs- und Organisationsrollen aus Ihrer Anwendung ab. Weitere Informationen finden Sie unter Verwalten von IoT Central-Organisationen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus, das die IDs der Anwendungs- und der Organisationsrolle 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": "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"
        }
    ]
}

Erstellen eines API-Tokens, das an einen Knoten angefügt ist, in einer Organisationshierarchie

Erstellen Sie mithilfe der folgenden Anforderung ein API-Token, das an einen Knoten in einer Organisationshierarchie in Ihrer Anwendung angefügt ist:

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

Das folgende Beispiel zeigt einen Anforderungstext, der ein API-Token für die Organisation seattle in einer IoT Central-Anwendung erstellt.

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

Der Anforderungstext enthält einige erforderliche Felder:

Name Beschreibung
role ID einer der Organisationsrollen
organization ID der Organisation

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

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

Zuordnen eines Benutzers zu einem Knoten in einer Organisationshierarchie

Mithilfe der folgenden Anforderung können Sie einen Benutzer erstellen und einem Knoten in einer Organisationshierarchie in Ihrer Anwendung zuordnen. 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 role für die ID einer der Organisationsrollen und organization für die ID der Organisation.

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

Hinzufügen und Zuordnen eines Geräts zu einer Organisation

Verwenden der folgenden Anforderung zum Zuordnen eines neuen Geräts zu einer Organisation.

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

Das folgende Beispiel zeigt einen Anforderungstext, der ein Gerät für eine Gerätevorlage hinzufügt. Die template-Details können Sie auf der Seite für Gerätevorlagen auf der Benutzeroberfläche der IoT Central-Anwendung abrufen.

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

Der Anforderungstext enthält einige erforderliche Felder:

  • @displayName: Dies ist der Anzeigename des Geräts.
  • @enabled: deklariert dieses Objekt als Schnittstelle
  • @etag: Dies ist das ETag, das verwendet wird, um Konflikte bei Geräteupdates zu verhindern.
  • simulated: Wird das Gerät simuliert?
  • template : Dies ist die Gerätevorlagendefinition für das Gerät.
  • organizations: Liste der Organisations-IDs, zu denen das Gerät gehört. Derzeit können Sie ein Gerät nur einer einzelnen Organisation zuordnen.

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

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

}

Hinzufügen und Zuordnen einer Gerätegruppe zu einer Organisation

Mithilfe der folgenden Anforderung können Sie eine neue Gerätegruppe erstellen und einer Organisation zuordnen.

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

Wenn Sie eine Gerätegruppe erstellen, definieren Sie einen filter, der die Geräte auswählt, die der Gruppe hinzugefügt werden sollen. Eine filter identifiziert eine Gerätevorlage und alle Eigenschaften, die übereinstimmen sollen. Im folgenden Beispiel wird eine Gerätegruppe erstellt, die alle zur Vorlage dtmi:modelDefinition:dtdlv2 passenden Geräte enthält, wobei die Eigenschaft provisioned TRUE ist.

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

Der Anforderungstext enthält einige erforderliche Felder:

  • @displayName: Anzeigename der Gerätegruppe.
  • @filter: Abfrage, die definiert, welche Geräte in dieser Gruppe enthalten sein sollen.
  • description: Kurze Zusammenfassung der Gerätegruppe.
  • organizations: Liste der Organisations-IDs, zu denen das Gerät gehört. Derzeit können Sie ein Gerät nur einer einzelnen Organisation zuordnen.

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

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

Nächste Schritte

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