Ověřování a autorizace volání rozhraní IoT Central REST API

Článek
03/05/2024

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. Pomocí rozhraní REST API můžete pracovat s prostředky ve vaší aplikaci IoT Central, jako jsou šablony zařízení, zařízení, úlohy, uživatelé a role.

Každé volání rozhraní REST API služby IoT Central vyžaduje autorizační hlavičku, kterou IoT Central používá k určení identity volajícího a oprávnění, která volajícímu udělí v rámci aplikace.

Tento článek popisuje typy tokenů, které můžete použít v autorizační hlavičce a jak je získat. Instanční objekty jsou doporučeným přístupem pro správu přístupu k rozhraní REST API služby IoT Central.

Typy tokenů

Pokud chcete získat přístup k aplikaci IoT Central pomocí rozhraní REST API, můžete použít:

Nosný token Microsoft Entra. Nosný token je přidružený k uživatelskému účtu Microsoft Entra nebo instančnímu objektu. Token volajícímu udělí stejná oprávnění, která má uživatel nebo instanční objekt v aplikaci IoT Central.
Token rozhraní API IoT Central Token rozhraní API je přidružený k roli ve vaší aplikaci IoT Central.

Při vývoji a testování automatizace a skriptů, které používají rozhraní REST API, použijte nosný token přidružený k vašemu uživatelskému účtu. Pro produkční automatizaci a skripty použijte nosný token přidružený k instančnímu objektu. Použijte nosný token v předvolbě tokenu rozhraní API, abyste snížili riziko úniku a problémů při vypršení platnosti tokenů.

Další informace o uživatelích a rolích v IoT Central najdete v tématu Správa uživatelů a rolí v aplikaci IoT Central.

Získání nosné tokeny

Pokud chcete získat nosný token pro uživatelský účet Microsoft Entra, použijte následující příkazy Azure CLI:

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

Důležité

Příkaz az login je nutný i v případě, že používáte Cloud Shell.

Výstup JSON z předchozího příkazu vypadá jako v následujícím příkladu:

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

Nosný token je platný přibližně jednu hodinu, po které potřebujete vytvořit nový token.

Pokud chcete získat nosný token pro instanční objekt, přečtěte si téma Ověřování instančního objektu.

Získání tokenu rozhraní API

K získání tokenu rozhraní API můžete použít uživatelské rozhraní IoT Central nebo volání rozhraní REST API. Správa istrátory přidružené ke kořenové organizaci a uživatelům přiřazeným ke správné roli můžou vytvářet tokeny rozhraní API.

Tip

Operace vytvoření a odstranění tokenů rozhraní API se zaznamenávají v protokolu auditu.

V uživatelském rozhraní IoT Central:

Přejděte na tokeny rozhraní API pro oprávnění>.
Vyberte + Nový nebo Vytvořit token rozhraní API.
Zadejte název tokenu a vyberte roli a organizaci.
Vyberte Generovat.
IoT Central zobrazí token, který vypadá jako v následujícím příkladu:

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

Tato obrazovka je jediný čas, kdy uvidíte token rozhraní API, pokud ho ztratíte, potřebujete vygenerovat nový.

Token rozhraní API je platný přibližně jeden rok. Tokeny můžete vygenerovat pro předdefinované i vlastní role v aplikaci IoT Central. Organizace, kterou zvolíte při vytváření tokenu rozhraní API, určuje, ke kterým zařízením má rozhraní API přístup. Všechny tokeny rozhraní API vytvořené před přidáním organizace do vaší aplikace jsou přidružené ke kořenové organizaci.

Pokud potřebujete odvolat přístup, můžete v uživatelském rozhraní IoT Central odstranit tokeny rozhraní API.

Použití rozhraní REST API:

K načtení seznamu ID rolí z vaší aplikace použijte rozhraní REST API:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pomocí rozhraní REST API vytvořte token rozhraní API pro roli. Pokud například chcete vytvořit token rozhraní API volaný operator-token pro roli operátora:

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

Text požadavku:

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

Odpověď na předchozí příkaz vypadá jako následující JSON:

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

Tato odpověď je jediný čas, kdy máte přístup k tokenu rozhraní API, pokud ho ztratíte, potřebujete vygenerovat nový.

Rozhraní REST API můžete použít k výpisu a odstranění tokenů rozhraní API v aplikaci.

Použití nosný token

Pokud chcete použít nosný token při volání rozhraní REST API, vaše autorizační hlavička vypadá jako v následujícím příkladu:

Authorization: Bearer eyJ0eX...fNQ

Použití tokenu rozhraní API

Pokud chcete použít token rozhraní API při volání rozhraní REST API, vaše autorizační hlavička vypadá jako v následujícím příkladu:

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

Sdílet prostřednictvím