Dela via

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

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.

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:

Name beskrivning
roll ID för en av organisationsrollerna
organization 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.