Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central

Artykuł
03/05/2024

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 pracę z zasobami w aplikacji usługi IoT Central, takimi jak szablony urządzeń, urządzenia, zadania, użytkownicy i role.

Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji używanego przez usługę IoT Central do określenia tożsamości obiektu wywołującego i uprawnień, które obiekt wywołujący jest udzielany w aplikacji.

W tym artykule opisano typy tokenów, których można użyć w nagłówku autoryzacji, oraz sposób ich pobierania. Jednostki usługi to zalecane podejście do zarządzania dostępem do interfejsu API REST usługi IoT Central.

Typy tokenów

Aby uzyskać dostęp do aplikacji usługi IoT Central przy użyciu interfejsu API REST, możesz użyć:

Token elementu nośnego Entra firmy Microsoft. Token elementu nośnego jest skojarzony z kontem użytkownika firmy Microsoft Entra lub jednostką usługi. Token przyznaje obiekt wywołujący te same uprawnienia, które użytkownik lub jednostka usługi ma w aplikacji usługi IoT Central.
Token interfejsu API usługi IoT Central. Token interfejsu API jest skojarzony z rolą w aplikacji usługi IoT Central.

Użyj tokenu elementu nośnego skojarzonego z kontem użytkownika podczas tworzenia i testowania automatyzacji i skryptów korzystających z interfejsu API REST. Użyj tokenu elementu nośnego skojarzonego z jednostką usługi na potrzeby automatyzacji produkcji i skryptów. Użyj tokenu elementu nośnego w preferencjach do tokenu interfejsu API, aby zmniejszyć ryzyko wycieków i problemów po wygaśnięciu tokenów.

Aby dowiedzieć się więcej o użytkownikach i rolach w usłudze IoT Central, zobacz Zarządzanie użytkownikami i rolami w aplikacji usługi IoT Central.

Uzyskiwanie tokenu elementu nośnego

Aby uzyskać token elementu nośnego dla konta użytkownika usługi Microsoft Entra, użyj następujących poleceń interfejsu wiersza polecenia platformy Azure:

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

Ważne

To az login polecenie jest konieczne, nawet jeśli używasz usługi Cloud Shell.

Dane wyjściowe JSON z poprzedniego polecenia wyglądają jak w poniższym przykładzie:

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

Token elementu nośnego jest ważny przez około godzinę, po którym należy utworzyć nowy.

Aby uzyskać token elementu nośnego dla jednostki usługi, zobacz Uwierzytelnianie jednostki usługi.

Pobieranie tokenu interfejsu API

Aby uzyskać token interfejsu API, możesz użyć interfejsu użytkownika usługi IoT Central lub wywołania interfejsu API REST. Administracja istratory skojarzone z organizacją główną i użytkownikami przypisanymi do odpowiedniej roli mogą tworzyć tokeny interfejsu API.

Napiwek

Operacje tworzenia i usuwania tokenów interfejsu API są rejestrowane w dzienniku inspekcji.

W interfejsie użytkownika usługi IoT Central:

Przejdź do pozycji Tokeny interfejsu API uprawnień>.
Wybierz pozycję + Nowy lub Utwórz token interfejsu API.
Wprowadź nazwę tokenu i wybierz rolę i organizację.
Wybierz Generuj.
Usługa IoT Central wyświetla token podobny do następującego przykładu:

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

Ten ekran jest jedynym czasem, w którym można zobaczyć token interfejsu API, jeśli utracisz go, musisz wygenerować nowy.

Token interfejsu API jest ważny przez około rok. Tokeny dla ról wbudowanych i niestandardowych można wygenerować w aplikacji usługi IoT Central. Organizacja wybrana podczas tworzenia tokenu interfejsu API określa, do których urządzeń ma dostęp interfejs API. Wszystkie tokeny interfejsu API utworzone przed dodaniem organizacji do aplikacji są skojarzone z organizacją główną.

Jeśli chcesz odwołać dostęp, możesz usunąć tokeny interfejsu API w interfejsie użytkownika usługi IoT Central.

Przy użyciu interfejsu API REST:

Użyj interfejsu API REST, aby pobrać listę identyfikatorów ról z aplikacji:

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

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

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

Użyj interfejsu API REST, aby utworzyć token interfejsu API dla roli. Aby na przykład utworzyć token interfejsu API wywoływany operator-token dla roli operatora:

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

Treść żądania:

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

Odpowiedź na poprzednie polecenie wygląda następująco:

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

Ta odpowiedź jest jedyną odpowiedzią, gdy masz dostęp do tokenu interfejsu API, jeśli utracisz go, musisz wygenerować nowy.

Interfejs API REST umożliwia wyświetlanie listy i usuwanie tokenów interfejsu API w aplikacji.

Używanie tokenu elementu nośnego

Aby użyć tokenu elementu nośnego podczas wywołania interfejsu API REST, nagłówek autoryzacji wygląda jak w poniższym przykładzie:

Authorization: Bearer eyJ0eX...fNQ

Używanie tokenu interfejsu API

Aby użyć tokenu interfejsu API podczas wywołania interfejsu API REST, nagłówek autoryzacji wygląda następująco:

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

Share via