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

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:

  1. Navigáljon az Engedélyek > API-jogkivonatokhoz.

  2. Válassza az + Új vagy API-jogkivonat létrehozása lehetőséget.

  3. Adja meg a jogkivonat nevét, és válasszon ki egy szerepkört és egy szervezetet.

  4. Válassza a Létrehozás lehetőséget.

  5. 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:

  1. 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"
        }
      ]
    }
    
  2. 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