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:dtdlv2 provisioned 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.