Megosztás a következőn keresztül:

Az IoT Central REST API használata szervezetek kezeléséhez

  • Cikk

Az IoT Central REST API lehetővé teszi az IoT Central-alkalmazásokkal integrálható ügyfélalkalmazások fejlesztését. A REST API-val kezelheti az IoT Central-alkalmazásban lévő szervezeteket.

Minden IoT Central REST API-híváshoz szükség van egy engedélyezési fejlécre. További információ: IoT Central REST API-hívások hitelesítése és engedélyezése.

Az IoT Central REST API referenciadokumentációját az Azure IoT Central REST API-referenciájában találja.

Az IoT Central-alkalmazásokban található szervezetekről az IoT Central-szervezetek kezelése című témakörben olvashat bővebben.

Tipp.

A Postman használatával kipróbálhatja a cikkben ismertetett REST API-hívásokat. Töltse le az IoT Central Postman gyűjteményt , és importálja a Postmanbe. A gyűjteményben olyan változókat kell beállítania, mint az alkalmazás altartománya és a rendszergazdai jogkivonat.

Szervezetek REST API

Az IoT Central REST API használatával a következőket teheti:

  • Szervezet hozzáadása az alkalmazáshoz
  • Szervezet lekérése azonosító alapján
  • Szervezet frissítése az alkalmazásban
  • Az alkalmazásban lévő szervezetek listájának lekérése
  • Szervezet törlése az alkalmazásban

Szervezetek létrehozása

A REST API-val szervezeteket hozhat létre az IoT Central-alkalmazásban. A következő kéréssel hozzon létre egy szervezetet az alkalmazásban:

PUT https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31
  • organizationId – A szervezet egyedi azonosítója

Az alábbi példa egy olyan kérelemtörzset mutat be, amely egy szervezetet ad hozzá egy IoT Central-alkalmazáshoz.

{
  "displayName": "Seattle",
}

A kérelem törzse tartalmaz néhány kötelező mezőt:

  • @displayName: A szervezet megjelenítendő neve.

A kérelem törzse néhány választható mezővel rendelkezik:

  • @parent: A szervezet szülőjének azonosítója.

Ha nem ad meg szülőt, akkor a szervezet az alapértelmezett legfelső szintű szervezetet kapja szülőként.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Létrehozhat egy hierarchiával rendelkező szervezetet, például létrehozhat egy értékesítési szervezetet egy szülőszervezettel.

Az alábbi példa egy olyan kérelemtörzset mutat be, amely egy szervezetet ad hozzá egy IoT Central-alkalmazáshoz.

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Szervezet lekérése

Az alábbi kéréssel lekérheti egy adott szervezet adatait az alkalmazásból:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Szervezet frissítése

A következő kéréssel frissítheti egy szervezet adatait az alkalmazásban:

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

Az alábbi példa egy olyan kéréstörzset mutat be, amely frissíti a szervezet szülőját:

{
  "parent": "washington"
}

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Szervezetek listázása

A következő kéréssel lekérheti a szervezetek listáját az alkalmazásból:

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

A kérésre adott válasz az alábbi példához hasonlóan néz ki.

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

A Washington, Redmond és Bellevue szervezetek automatikusan az alkalmazás alapértelmezett legfelső szintű szervezetével rendelkeznek szülőként.

Szervezet törlése

A következő kéréssel törölhet egy szervezetet:

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

Szervezetek használata

A szervezetek segítségével kezelheti az alkalmazás erőforrásaihoz való hozzáférést.

Szerepkörök kezelése

A REST API-val listázhatja az IoT Central-alkalmazásban definiált szerepköröket. Az alábbi kéréssel lekérheti az alkalmazás szerepköreinek és szervezeti szerepkör-azonosítóinak listáját az alkalmazásból. További információ: IoT Central-szervezetek kezelése:

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

A kérésre adott válasz az alábbi példához hasonlóan jelenik meg, amely tartalmazza az alkalmazásszerepkört és a szervezeti szerepkör azonosítóit.

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

Szervezeti hierarchiában lévő csomóponthoz csatolt API-jogkivonat létrehozása

A következő kéréssel hozzon létre egy api-jogkivonatot, amely egy szervezeti hierarchia egyik csomópontjához van csatolva az alkalmazásban:

PUT https://{your app subdomain}.azureiotcentral.com/api/apiTokens/{tokenId}?api-version=2022-07-31
  • tokenId – A jogkivonat egyedi azonosítója

Az alábbi példa egy kéréstörzset mutat be, amely létrehoz egy API-jogkivonatot a seattle-i szervezet számára egy IoT Central-alkalmazásban.

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

Name Leírás
szerepkör Az egyik szervezeti szerepkör azonosítója
szervezet A szervezet azonosítója

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Felhasználó társítása egy szervezeti hierarchiában lévő csomóponttal

A következő kéréssel létrehozhat és társíthat egy felhasználót egy szervezeti hierarchia egy csomópontjával az alkalmazásban. Az azonosítónak és az e-mailnek egyedinek kell lennie az alkalmazásban:

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

A következő kérelemtörzsben az role egyik szervezeti szerepkör azonosítója, és organization a szervezet azonosítója.

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

}

A kérésre adott válasz az alábbi példához hasonlóan néz ki. A szerepkör értéke azonosítja, hogy a felhasználó melyik szerepkörhöz van társítva:

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

Eszköz hozzáadása és társítása egy szervezethez

Az alábbi kéréssel társíthat egy új eszközt egy szervezethez

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

Az alábbi példa egy olyan kéréstörzset mutat be, amely egy eszközsablonhoz ad hozzá eszközt. A részleteket az template IoT Central-alkalmazás felhasználói felületén található eszközsablonok oldaláról szerezheti be.

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

  • @displayName: Az eszköz megjelenítendő neve.
  • @enabled: deklarálja, hogy ez az objektum egy interfész.
  • @etag: Az eszközfrissítések ütközésének megelőzésére szolgáló ETag.
  • simulated: Az eszköz szimulálva van?
  • template : Az eszköz eszközsablon-definíciója.
  • organizations : Azoknak a szervezeti azonosítóknak a listája, amelyeknek az eszköz része. Jelenleg csak egyetlen szervezethez társíthat eszközöket.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

}

Eszközcsoport hozzáadása és társítása egy szervezethez

Az alábbi kéréssel létrehozhat és társíthat egy új eszközcsoportot egy szervezettel.

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

Amikor létrehoz egy eszközcsoportot, meghatároz egy filter olyan eszközt, amely kiválasztja a csoporthoz hozzáadni kívánt eszközöket. Az A filter azonosítja az eszközsablont és az egyező tulajdonságokat. Az alábbi példa olyan eszközcsoportot hoz létre, amely tartalmazza a dtmi:modelDefinition:dtdlv2 sablonhoz társított összes eszközt, ahol a provisioned tulajdonság igaz.

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

A kérelem törzse tartalmaz néhány kötelező mezőt:

  • @displayName: Az eszközcsoport megjelenítendő neve.
  • @filter: Lekérdezés, amely meghatározza, hogy mely eszközök legyenek ebben a csoportban.
  • description: Az eszközcsoport rövid összefoglalása.
  • organizations : Azoknak a szervezeti azonosítóknak a listája, amelyeknek az eszköz része. Jelenleg csak egyetlen szervezethez társíthat eszközöket.

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Következő lépések

Most, hogy megtanulta, hogyan kezelheti a szervezeteket a REST API-val, javasolt következő lépés az IoT Central REST API használata az adatexportok kezeléséhez.