Udostępnij za pośrednictwem

Jak zarządzać organizacjami przy użyciu interfejsu API REST usługi IoT Central

  • Artykuł

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 organizacjami 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.

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

Aby dowiedzieć się więcej o organizacjach w aplikacji usługi IoT Central, zobacz Zarządzanie organizacjami usługi IoT Central.

Interfejs API REST organizacji

Interfejs API REST usługi IoT Central umożliwia wykonywanie następujących działań:

  • Dodawanie organizacji do aplikacji
  • Pobieranie organizacji według identyfikatora
  • Aktualizowanie organizacji w aplikacji
  • Pobieranie listy organizacji w aplikacji
  • Usuwanie organizacji w aplikacji

Tworzenie organizacji

Interfejs API REST umożliwia tworzenie organizacji w aplikacji usługi IoT Central. Użyj następującego żądania, aby utworzyć organizację w aplikacji:

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

W poniższym przykładzie przedstawiono treść żądania, która dodaje organizację do aplikacji usługi IoT Central.

{
  "displayName": "Seattle",
}

Treść żądania zawiera kilka wymaganych pól:

  • @displayName: Nazwa wyświetlana organizacji.

Treść żądania zawiera kilka pól opcjonalnych:

  • @parent: identyfikator elementu nadrzędnego organizacji.

Jeśli nie określisz elementu nadrzędnego, organizacja otrzyma domyślną organizację najwyższego poziomu jako nadrzędną.

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

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

Możesz utworzyć organizację z hierarchią, na przykład utworzyć organizację sprzedaży z organizacją nadrzędną.

W poniższym przykładzie przedstawiono treść żądania, która dodaje organizację do aplikacji usługi IoT Central.

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

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

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

Uzyskiwanie organizacji

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

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

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

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

Aktualizowanie organizacji

Użyj następującego żądania, aby zaktualizować szczegóły organizacji w aplikacji:

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

W poniższym przykładzie przedstawiono treść żądania, która aktualizuje element nadrzędny organizacji:

{
  "parent": "washington"
}

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

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

Wyświetlanie listy organizacji

Użyj następującego żądania, aby pobrać listę organizacji z aplikacji:

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

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu.

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

Organizacje Washington, Redmond i Bellevue automatycznie mają domyślną organizację najwyższego poziomu aplikacji jako nadrzędną.

Usuwanie organizacji

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

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

Korzystanie z organizacji

Użyj organizacji, aby zarządzać dostępem do zasobów w aplikacji.

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 aplikacji i organizacji z aplikacji. Aby dowiedzieć się więcej, zobacz Jak zarządzać organizacjami usługi IoT Central:

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

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu, który zawiera identyfikatory roli aplikacji i roli organizacji.

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

Tworzenie tokenu interfejsu API dołączonego do węzła w hierarchii organizacji

Użyj następującego żądania, aby utworzyć token interfejsu API dołączony do węzła w hierarchii organizacji w aplikacji:

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

Poniższy przykład przedstawia treść żądania, która tworzy token interfejsu API dla organizacji seattle w aplikacji usługi IoT Central.

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

Treść żądania zawiera kilka wymaganych pól:

Nazwa/nazwisko opis
role Identyfikator jednej z ról organizacji
organization Identyfikator organizacji

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

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

Kojarzenie użytkownika z węzłem w hierarchii organizacji

Użyj następującego żądania, aby utworzyć i skojarzyć użytkownika z węzłem w hierarchii organizacji 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 jest identyfikatorem jednej z ról organizacji i organization jest identyfikatorem organizacji

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

Dodawanie i kojarzenie urządzenia z organizacją

Użyj następującego żądania, aby skojarzyć nowe urządzenie z organizacją

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

Poniższy przykład przedstawia treść żądania, która dodaje urządzenie dla szablonu urządzenia. Szczegółowe informacje można uzyskać template na stronie szablonów urządzeń w interfejsie użytkownika aplikacji usługi IoT Central.

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

Treść żądania zawiera kilka wymaganych pól:

  • @displayName: nazwa wyświetlana urządzenia.
  • @enabled: deklaruje, że ten obiekt jest interfejsem.
  • @etag: Element ETag używany do zapobiegania konfliktom w aktualizacjach urządzeń.
  • simulated: Czy urządzenie jest symulowane?
  • template : definicja szablonu urządzenia dla urządzenia.
  • organizations : lista identyfikatorów organizacji, których częścią jest urządzenie. Obecnie można skojarzyć urządzenie tylko z jedną organizacją.

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

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

}

Dodawanie i kojarzenie grupy urządzeń z organizacją

Użyj następującego żądania, aby utworzyć i skojarzyć nową grupę urządzeń z organizacją.

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

Podczas tworzenia grupy urządzeń należy zdefiniować element filter , który wybiera urządzenia do dodania do grupy. Element filter identyfikuje szablon urządzenia i wszystkie właściwości, które mają być zgodne. Poniższy przykład obejmuje tworzenie grupy urządzeń zawierającej wszystkie urządzenia skojarzone z szablonem dtmi:modelDefinition:dtdlv2 , w provisioned którym właściwość ma wartość true.

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

Treść żądania zawiera kilka wymaganych pól:

  • @displayName: Nazwa wyświetlana grupy urządzeń.
  • @filter: Kwerenda definiująca, które urządzenia powinny znajdować się w tej grupie.
  • description: krótkie podsumowanie grupy urządzeń.
  • organizations : lista identyfikatorów organizacji, których częścią jest urządzenie. Obecnie można skojarzyć urządzenie tylko z jedną organizacją.

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

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

Następne kroki

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