Så här använder du IoT Central REST API för att hantera organisationer

Artikel
05/24/2023

Med REST API för IoT Central kan du utveckla klientprogram som integreras med IoT Central-program. Du kan använda REST-API:et för att hantera organisationer i ditt IoT Central-program.

Varje IoT Central REST API-anrop kräver ett auktoriseringshuvud. Mer information finns i Autentisera och auktorisera IoT Central REST API-anrop.

Referensdokumentationen för REST API:et för IoT Central finns i Referens för Rest API för Azure IoT Central.

Mer information om organisationer i IoT Central Application finns i Hantera IoT Central-organisationer.

Dricks

Du kan använda Postman för att prova REST API-anropen som beskrivs i den här artikeln. Ladda ned IoT Central Postman-samlingen och importera den till Postman. I samlingen måste du ange variabler som appens underdomän och administratörstoken.

REST API för organisationer

I REST-API:et för IoT Central kan du göra följande:

Lägga till en organisation i ditt program
Hämta en organisation efter ID
Uppdatera en organisation i ditt program
Hämta en lista över organisationer i programmet
Ta bort en organisation i ditt program

Skapa organisationer

Med REST-API:et kan du skapa organisationer i ditt IoT Central-program. Använd följande begäran för att skapa en organisation i ditt program:

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

organizationId – Unikt ID för organisationen

I följande exempel visas en begärandetext som lägger till en organisation i ett IoT Central-program.

{
  "displayName": "Seattle",
}

Begärandetexten innehåller några obligatoriska fält:

@displayName: Organisationens visningsnamn.

Begärandetexten innehåller några valfria fält:

@parent: ID för den överordnade organisationen.

Om du inte anger en överordnad organisation får organisationen den högsta standardorganisationen som överordnad.

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

{
  "id": "seattle",
  "displayName": "Seattle"
}

Du kan skapa en organisation med hierarki, till exempel kan du skapa en försäljningsorganisation med en överordnad organisation.

I följande exempel visas en begärandetext som lägger till en organisation i ett IoT Central-program.

{
  "displayName": "Sales",
  "parent":"seattle"
}

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

{
  "id": "sales",
  "displayName": "Sales",
  "parent":"Seattle"
}

Hämta en organisation

Använd följande begäran för att hämta information om en enskild organisation från ditt program:

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

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

{
  "id": "seattle",
  "displayName": "Seattle",
  "parent": "washington"
}

Uppdatera en organisation

Använd följande begäran för att uppdatera information om en organisation i ditt program:

PATCH https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

I följande exempel visas en begärandetext som uppdaterar den överordnade organisationen:

{
  "parent": "washington"
}

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

{
  "id": "seattle",
  "displayName": "Seattle Sales",
  "parent": "washington"
}

Lista organisationer

Använd följande begäran för att hämta en lista över organisationer från ditt program:

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

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

{
    "value": [
        {
            "id": "washington",
            "displayName": "Washington"
        },
        {
            "id": "redmond",
            "displayName": "Redmond"
        },
        {
            "id": "bellevue",
            "displayName": "Bellevue"
        },
        {
            "id": "spokane",
            "displayName": "Spokane",
            "parent": "washington"
        },
        {
            "id": "seattle",
            "displayName": "Seattle",
            "parent": "washington"
        }
    ]
}

Organisationerna Washington, Redmond och Bellevue har automatiskt programmets standardorganisation på toppnivå som förälder.

Ta bort en organisation

Använd följande begäran för att ta bort en organisation:

DELETE https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

Använda organisationer

Använd organisationer för att hantera åtkomst till resurser i ditt program.

Hantera roller

Med REST-API:et kan du visa en lista över de roller som definierats i ditt IoT Central-program. Använd följande begäran för att hämta en lista över programroll- och organisationsroll-ID:t från ditt program. Mer information finns i Hantera IoT Central-organisationer:

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 som innehåller programrollen och organisationsroll-ID:erna.

{
    "value": [
        {
            "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
            "displayName": "Administrator"
        },
        {
            "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
            "displayName": "Operator"
        },
        {
            "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
            "displayName": "Builder"
        },
        {
            "id": "c495eb57-eb18-489e-9802-62c474e5645c",
            "displayName": "Org Admin"
        },
        {
            "id": "b4935647-30e4-4ed3-9074-dcac66c2f8ef",
            "displayName": "Org Operator"
        },
        {
            "id": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "displayName": "Org Viewer"
        }
    ]
}

Skapa en API-token som är kopplad till en nod i en organisationshierarki

Använd följande begäran för att skapa Skapa en API-token som är kopplad till en nod i en organisationshierarki i ditt program:

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

tokenId – Unikt ID för token

I följande exempel visas en begärandetext som skapar en API-token för seattle-organisationen i ett IoT Central-program.

{
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ]
}

Begärandetexten innehåller några obligatoriska fält:

Namn	Beskrivning
roll	ID för en av organisationsrollerna
organisation	ID för organisationen

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

{
    "id": "token1",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "expiry": "2023-07-07T17:05:08.407Z",
    "token": "SharedAccessSignature sr=8a0617**********************4c0d71c&sig=3RyX69G4%2FBZZnG0LXOjQv*************e8s%3D&skn=token1&se=1688749508407"
}

Associera en användare med en nod i en organisationshierarki

Använd följande begäran för att skapa och associera en användare med en nod i en organisationshierarki i ditt program. ID:t och e-postmeddelandet måste vara unika i programmet:

PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

I följande begärandetext role är ID för en av organisationens roller och organization är ID för organisationen

{
  "id": "user-001",
  "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"

}

Svaret på den här begäran ser ut som i följande exempel. Rollvärdet identifierar vilken roll användaren är associerad med:

{
    "id": "user-001",
    "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"
}

Lägga till och associera en enhet till en organisation

Använd följande begäran för att associera en ny enhet med en organisation

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

I följande exempel visas en begärandetext som lägger till en enhet för en enhetsmall. Du kan hämta template informationen från sidan med enhetsmallar i IoT Central-programgränssnittet.

{
    "displayName": "CheckoutThermostat",
    "template": "dtmi:contoso:Thermostat;1",
    "simulated": true,
    "enabled": true,
    "organizations": [
        "seattle"
    ]
}

Begärandetexten innehåller några obligatoriska fält:

@displayName: Enhetens visningsnamn.
@enabled: deklarerar att det här objektet är ett gränssnitt.
@etag: ETag används för att förhindra konflikter i enhetsuppdateringar.
simulated: Simuleras enheten?
template : Enhetsmalldefinitionen för enheten.
organizations : Lista över organisations-ID:n som enheten ingår i. För närvarande kan du bara associera en enhet med en enda organisation.

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true,
   "organizations": [
    "seattle"
  ]

}

Lägga till och associera en enhetsgrupp till en organisation

Använd följande begäran för att skapa och associera en ny enhetsgrupp med en organisation.

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

När du skapar en enhetsgrupp definierar du en filter som väljer de enheter som ska läggas till i gruppen. En filter identifierar en enhetsmall och eventuella egenskaper som ska matchas. I följande exempel skapas en enhetsgrupp som innehåller alla enheter som är associerade med mallen dtmi:modelDefinition:dtdlv2provisioned där egenskapen är sann.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Begärandetexten innehåller några obligatoriska fält:

@displayName: Enhetsgruppens visningsnamn.
@filter: Fråga som definierar vilka enheter som ska finnas i den här gruppen.
description: Kort sammanfattning av enhetsgrupp.
organizations : Lista över organisations-ID:n som enheten ingår i. För närvarande kan du bara associera en enhet med en enda organisation.

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

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Nästa steg

Nu när du har lärt dig hur du hanterar organisationer med REST-API:et är ett föreslaget nästa steg att använda REST-API:et i IoT Central för att hantera dataexporter.

Share via

Så här använder du IoT Central REST API för att hantera organisationer

REST API för organisationer

Skapa organisationer

Hämta en organisation

Uppdatera en organisation

Lista organisationer

Ta bort en organisation

Använda organisationer

Hantera roller

Skapa en API-token som är kopplad till en nod i en organisationshierarki

Associera en användare med en nod i en organisationshierarki

Lägga till och associera en enhet till en organisation

Lägga till och associera en enhetsgrupp till en organisation

Nästa steg

Ytterligare resurser