Delen via

De Rest API van IoT Central gebruiken om organisaties te beheren

  • Artikel

Met de REST API van IoT Central kunt u clienttoepassingen ontwikkelen die kunnen worden geïntegreerd met IoT Central-toepassingen. U kunt de REST API gebruiken om organisaties in uw IoT Central-toepassing te beheren.

Elke IoT Central REST API-aanroep vereist een autorisatieheader. Zie IoT Central REST API-aanroepen verifiëren en autoriseren voor meer informatie.

Zie de naslaginformatie voor de REST API van IoT Central voor Azure IoT Central.

Zie IoT Central-organisaties beheren voor meer informatie over organisaties in de IoT Central-toepassing.

Fooi

U kunt Postman gebruiken om de REST API-aanroepen uit te proberen die in dit artikel worden beschreven. Download de IoT Central Postman-verzameling en importeer deze in Postman. In de verzameling moet u variabelen instellen, zoals uw app-subdomein en het beheertoken.

REST API voor organisaties

Met behulp van de REST API van IoT Central kunt u:

  • Een organisatie toevoegen aan uw toepassing
  • Een organisatie ophalen op id
  • Een organisatie bijwerken in uw toepassing
  • Een lijst ophalen van de organisaties in de toepassing
  • Een organisatie verwijderen in uw toepassing

Organisaties maken

Met de REST API kunt u organisaties maken in uw IoT Central-toepassing. Gebruik de volgende aanvraag om een organisatie te maken in uw toepassing:

PUT https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31
  • organizationId - Unieke id van de organisatie

In het volgende voorbeeld ziet u een aanvraagbody waarmee een organisatie wordt toegevoegd aan een IoT Central-toepassing.

{
  "displayName": "Seattle",
}

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

  • @displayName: Weergavenaam van de organisatie.

De hoofdtekst van de aanvraag bevat enkele optionele velden:

  • @parent: id van het bovenliggende item van de organisatie.

Als u geen bovenliggend item opgeeft, krijgt de organisatie de standaardorganisatie op het hoogste niveau als bovenliggend item.

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

U kunt een organisatie maken met een hiërarchie, bijvoorbeeld u kunt een verkooporganisatie maken met een bovenliggende organisatie.

In het volgende voorbeeld ziet u een aanvraagbody waarmee een organisatie wordt toegevoegd aan een IoT Central-toepassing.

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een organisatie ophalen

Gebruik de volgende aanvraag om details van een afzonderlijke organisatie op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een organisatie bijwerken

Gebruik de volgende aanvraag om de details van een organisatie in uw toepassing bij te werken:

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

In het volgende voorbeeld ziet u een aanvraagbody die het bovenliggende element van de organisatie bijwerkt:

{
  "parent": "washington"
}

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Organisaties vermelden

Gebruik de volgende aanvraag om een lijst met organisaties op te halen uit uw toepassing:

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

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld.

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

De organisaties Washington, Redmond en Bellevue hebben automatisch de standaardorganisatie op het hoogste niveau van de toepassing als hun bovenliggende organisatie.

Een organisatie verwijderen

Gebruik de volgende aanvraag om een organisatie te verwijderen:

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

Organisaties gebruiken

Organisaties gebruiken om de toegang tot resources in uw toepassing te beheren.

Rollen beheren

Met de REST API kunt u de rollen weergeven die zijn gedefinieerd in uw IoT Central-toepassing. Gebruik de volgende aanvraag om een lijst met toepassingsrol- en organisatierol-id's op te halen uit uw toepassing. Zie IoT Central-organisaties beheren voor meer informatie:

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

Het antwoord op deze aanvraag lijkt op het volgende voorbeeld met de toepassingsrol en organisatierol-id's.

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

Een API-token maken dat is gekoppeld aan een knooppunt in een organisatiehiërarchie

Gebruik de volgende aanvraag om een API-token te maken dat is gekoppeld aan een knooppunt in een organisatiehiërarchie in uw toepassing:

PUT https://{your app subdomain}.azureiotcentral.com/api/apiTokens/{tokenId}?api-version=2022-07-31
  • tokenId - Unieke id van het token

In het volgende voorbeeld ziet u een aanvraagbody waarmee een API-token wordt gemaakt voor de organisatie seattle in een IoT Central-toepassing.

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

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

Naam Beschrijving
role Id van een van de organisatierollen
organization Id van de organisatie

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Een gebruiker koppelen aan een knooppunt in een organisatiehiërarchie

Gebruik de volgende aanvraag om een gebruiker te maken en te koppelen aan een knooppunt in een organisatiehiërarchie in uw toepassing. De id en het e-mailadres moeten uniek zijn in de toepassing:

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

In de volgende aanvraagbody is de role id van een van de organisatierollen en organization de id van de organisatie

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

}

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld. De rolwaarde bepaalt aan welke rol de gebruiker is gekoppeld:

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

Een apparaat toevoegen aan en koppelen aan een organisatie

Gebruik de volgende aanvraag om een nieuw apparaat te koppelen aan een organisatie

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

In het volgende voorbeeld ziet u een aanvraagbody waarmee een apparaat voor een apparaatsjabloon wordt toegevoegd. U kunt de template details ophalen op de pagina apparaatsjablonen in de gebruikersinterface van de IoT Central-toepassing.

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

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

  • @displayName: Weergavenaam van het apparaat.
  • @enabled: declareert dat dit object een interface is.
  • @etag: ETag gebruikt om conflicten in apparaatupdates te voorkomen.
  • simulated: Wordt het apparaat gesimuleerd?
  • template : De apparaatsjabloondefinitie voor het apparaat.
  • organizations : Lijst met organisatie-id's waarvan het apparaat deel uitmaakt. Op dit moment kunt u slechts een apparaat koppelen aan één organisatie.

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

}

Een apparaatgroep toevoegen aan en koppelen aan een organisatie

Gebruik de volgende aanvraag om een nieuwe apparaatgroep te maken en te koppelen aan een organisatie.

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

Wanneer u een apparaatgroep maakt, definieert u een filter apparaatgroep waarmee de apparaten worden geselecteerd die u aan de groep wilt toevoegen. A filter identificeert een apparaatsjabloon en eventuele eigenschappen die overeenkomen. In het volgende voorbeeld wordt een apparaatgroep gemaakt die alle apparaten bevat die zijn gekoppeld aan de dtmi:modelDefinition:dtdlv2 sjabloon waar de provisioned eigenschap waar is.

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

De hoofdtekst van de aanvraag bevat enkele vereiste velden:

  • @displayName: Weergavenaam van de apparaatgroep.
  • @filter: Query definiëren welke apparaten zich in deze groep moeten bevinden.
  • description: Korte samenvatting van apparaatgroep.
  • organizations : Lijst met organisatie-id's waarvan het apparaat deel uitmaakt. Op dit moment kunt u slechts een apparaat koppelen aan één organisatie.

Het antwoord op deze aanvraag ziet eruit als in het volgende voorbeeld:

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

Volgende stappen

Nu u hebt geleerd hoe u organisaties beheert met de REST API, is een voorgestelde volgende stap het gebruik van de IoT Central REST API voor het beheren van gegevensexports.