Autentisera och auktorisera IoT Central REST API-anrop

  • Artikel

Med REST API för IoT Central kan du utveckla klientprogram som integreras med IoT Central-program. Använd REST-API:et för att arbeta med resurser i ditt IoT Central-program, till exempel enhetsmallar, enheter, jobb, användare och roller.

Varje REST API-anrop i IoT Central kräver ett auktoriseringshuvud som IoT Central använder för att fastställa anroparens identitet och de behörigheter som anroparen beviljas i programmet.

Den här artikeln beskriver de typer av token som du kan använda i auktoriseringshuvudet och hur du hämtar dem. Tjänstens huvudnamn är den rekommenderade metoden för IoT Central REST API-åtkomsthantering.

Tokentyper

Om du vill komma åt ett IoT Central-program med hjälp av REST-API:et kan du använda en:

  • Microsoft Entra-ägartoken. En ägartoken är associerad med ett Microsoft Entra-användarkonto eller tjänstens huvudnamn. Token ger anroparen samma behörigheter som användaren eller tjänstens huvudnamn har i IoT Central-programmet.
  • IoT Central API-token. En API-token är associerad med en roll i ditt IoT Central-program.

Använd en ägartoken som är associerad med ditt användarkonto när du utvecklar och testar automatisering och skript som använder REST-API:et. Använd en ägartoken som är associerad med ett huvudnamn för tjänsten för produktionsautomation och skript. Använd en ägartoken i stället för en API-token för att minska risken för läckor och problem när token upphör att gälla.

Mer information om användare och roller i IoT Central finns i Hantera användare och roller i ditt IoT Central-program.

Hämta en ägartoken

Om du vill hämta en ägartoken för ditt Microsoft Entra-användarkonto använder du följande Azure CLI-kommandon:

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

Viktigt!

Kommandot az login är nödvändigt även om du använder Cloud Shell.

JSON-utdata från föregående kommando ser ut som i följande exempel:

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

Ägartoken är giltig i ungefär en timme, varefter du behöver skapa en ny.

Information om hur du hämtar en ägartoken för tjänstens huvudnamn finns i autentisering med tjänstens huvudnamn.

Hämta en API-token

Om du vill hämta en API-token kan du använda IoT Central-användargränssnittet eller ett REST API-anrop. Administratörer som är associerade med rotorganisationen och användare som tilldelats rätt roll kan skapa API-token.

Dricks

Skapa och ta bort åtgärder på API-token registreras i granskningsloggen.

I användargränssnittet för IoT Central:

  1. Gå till API-token för behörigheter>.

  2. Välj + Ny eller Skapa en API-token.

  3. Ange ett namn för token och välj en roll och organisation.

  4. Välj Generera.

  5. IoT Central visar den token som ser ut som i följande exempel:

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

    Den här skärmen är den enda gången du kan se API-token, om du förlorar den behöver du generera en ny.

En API-token är giltig i ungefär ett år. Du kan generera token för både inbyggda och anpassade roller i ditt IoT Central-program. Den organisation du väljer när du skapar API-token avgör vilka enheter SOM API:et har åtkomst till. Alla API-token som skapas innan du lägger till organisationer i ditt program är associerade med rotorganisationen.

Du kan ta bort API-token i IoT Central-användargränssnittet om du behöver återkalla åtkomsten.

Om du använder REST API:

  1. Använd REST-API:et för att hämta en lista över roll-ID:n från ditt program:

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

    Svaret på den här begäran ser ut som i följande exempel:

    {
  "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. Använd REST-API:et för att skapa en API-token för en roll. Om du till exempel vill skapa en API-token med namnet operator-token för operatorrollen:

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

    Begärandetext:

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

    Svaret på föregående kommando ser ut som följande 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"
}

    Det här svaret är den enda gången du har åtkomst till API-token, om du förlorar den behöver du generera en ny.

Du kan använda REST-API:et för att lista och ta bort API-token i ett program.

Använda en ägartoken

Om du vill använda en ägartoken när du gör ett REST API-anrop ser auktoriseringshuvudet ut som i följande exempel:

Authorization: Bearer eyJ0eX...fNQ

Använda en API-token

Om du vill använda en API-token när du gör ett REST API-anrop ser auktoriseringshuvudet ut som i följande exempel:

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