IoT Central REST API-hívások hitelesítése és engedélyezése

Cikk
03/05/2024

Az IoT Central REST API lehetővé teszi az IoT Central-alkalmazásokkal integrálható ügyfélalkalmazások fejlesztését. A REST API használatával használhatja az IoT Central-alkalmazás erőforrásait, például eszközsablonokat, eszközöket, feladatokat, felhasználókat és szerepköröket.

Minden IoT Central REST API-híváshoz szükség van egy engedélyezési fejlécre, amelyet az IoT Central használ a hívó identitásának és a hívó által az alkalmazásban megadott engedélyek meghatározásához.

Ez a cikk az engedélyezési fejlécben használható jogkivonat-típusokat és azok beszerzésének módját ismerteti. A szolgáltatásnevek az IoT Central REST API hozzáférés-kezelésének ajánlott megközelítései.

Jogkivonattípusok

Egy IoT Central-alkalmazás REST API-val való eléréséhez használhatja a következőt:

Microsoft Entra tulajdonosi jogkivonat. A tulajdonosi jogkivonat egy Microsoft Entra felhasználói fiókhoz vagy szolgáltatásnévhez van társítva. A jogkivonat ugyanazokat az engedélyeket adja a hívónak, mint a felhasználó vagy szolgáltatásnév az IoT Central-alkalmazásban.
IoT Central API-jogkivonat. Az API-jogkivonat egy szerepkörhöz van társítva az IoT Central-alkalmazásban.

Használjon a felhasználói fiókjához társított tulajdonosi jogkivonatot a REST API-t használó automatizálások és szkriptek fejlesztése és tesztelése során. Használjon egy szolgáltatásnévhez társított tulajdonosi jogkivonatot az éles automatizáláshoz és szkriptekhez. Használjon tulajdonosi jogkivonatot az API-jogkivonatok előnyben részesítéséhez a szivárgások és problémák kockázatának csökkentéséhez a jogkivonatok lejáratakor.

Az IoT Central felhasználóival és szerepköreivel kapcsolatos további információkért lásd : Felhasználók és szerepkörök kezelése az IoT Central-alkalmazásban.

Tulajdonosi jogkivonat lekérése

Ha tulajdonosi jogkivonatot szeretne lekérni a Microsoft Entra felhasználói fiókjához, használja az alábbi Azure CLI-parancsokat:

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Fontos

A az login parancsra akkor is szükség van, ha a Cloud Shellt használja.

Az előző parancs JSON-kimenete a következő példához hasonlóan néz ki:

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

A tulajdonosi jogkivonat körülbelül egy óráig érvényes, majd létre kell hoznia egy újat.

A szolgáltatásnév tulajdonosi jogkivonatának lekéréséhez tekintse meg a szolgáltatásnév hitelesítését.

API-jogkivonat lekérése

API-jogkivonat beszerzéséhez használhatja az IoT Central felhasználói felületét vagy egy REST API-hívást. A legfelső szintű szervezethez társított Rendszergazda istratorok és a megfelelő szerepkörhöz rendelt felhasználók API-jogkivonatokat hozhatnak létre.

Tipp.

Az API-jogkivonatokon végzett létrehozási és törlési műveleteket a napló rögzíti.

Az IoT Central felhasználói felületén:

Navigáljon az Engedélyek > API-jogkivonatokhoz.
Válassza az + Új vagy API-jogkivonat létrehozása lehetőséget.
Adja meg a jogkivonat nevét, és válasszon ki egy szerepkört és egy szervezetet.
Válassza a Létrehozás lehetőséget.
Az IoT Central az alábbi példához hasonló jogkivonatot jeleníti meg:

SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

Ez a képernyő az egyetlen alkalom, amikor láthatja az API-jogkivonatot, ha elveszíti azt, újat kell létrehoznia.

Az API-jogkivonat körülbelül egy évig érvényes. Az IoT Central-alkalmazásban a beépített és az egyéni szerepkörökhöz is létrehozhat jogkivonatokat. Az API-jogkivonat létrehozásakor kiválasztott szervezet határozza meg, hogy az API mely eszközökhöz fér hozzá. A szervezetek alkalmazáshoz való hozzáadása előtt létrehozott API-jogkivonatok a legfelső szintű szervezethez vannak társítva.

Ha vissza kell vonnia a hozzáférést, törölheti az API-jogkivonatokat az IoT Central felhasználói felületén.

A REST API-val:

A REST API-val lekérheti a szerepkör-azonosítók listáját az alkalmazásból:

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

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

{
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

A REST API használatával hozzon létre egy API-jogkivonatot egy szerepkörhöz. Például az operátori szerepkörhöz szükséges operator-token API-jogkivonat létrehozásához:

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

Kérés törzse:

{
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

Az előző parancsra adott válasz a következő JSON-hoz hasonlít:

{
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

Ez a válasz az egyetlen alkalom, amikor hozzáfér az API-jogkivonathoz, ha elveszíti azt, újat kell létrehoznia.

A REST API-val listázhatja és törölheti az API-jogkivonatokat egy alkalmazásban.

Tulajdonosi jogkivonat használata

Ha REST API-híváskor tulajdonosi jogkivonatot szeretne használni, az engedélyezési fejléc a következő példához hasonlóan néz ki:

Authorization: Bearer eyJ0eX...fNQ

API-jogkivonat használata

HA REST API-híváskor API-jogkivonatot szeretne használni, az engedélyezési fejléc a következő példához hasonlóan néz ki:

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889

Share via