Come usare l'API REST di IoT Central per gestire le organizzazioni

  • Articolo

L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. È possibile usare l'API REST per gestire le organizzazioni nell'applicazione IoT Central.

Ogni chiamata API REST di IoT Central richiede un'intestazione di autorizzazione. Per altre informazioni, vedere Come autenticare e autorizzare le chiamate API REST di IoT Central.

Per la documentazione di riferimento per l'API REST di IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.

Per altre informazioni sulle organizzazioni nell'applicazione IoT Central, vedere Gestire le organizzazioni IoT Central.

Suggerimento

È possibile usare Postman per provare le chiamate API REST descritte in questo articolo. Scaricare la raccolta Postman di IoT Central e importarla in Postman. Nella raccolta sarà necessario impostare variabili come il sottodominio dell'app e il token di amministratore.

API REST delle organizzazioni

L'API REST di IoT Central consente di:

  • Aggiungere un'organizzazione all'applicazione
  • Ottenere un'organizzazione in base all'ID
  • Aggiornare un'organizzazione nell'applicazione
  • Ottenere un elenco delle organizzazioni nell'applicazione
  • Eliminare un'organizzazione nell'applicazione

Creare organizzazioni

L'API REST consente di creare organizzazioni nell'applicazione IoT Central. Usare la richiesta seguente per creare un'organizzazione nell'applicazione:

PUT https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31
  • organizationId - ID univoco dell'organizzazione

L'esempio seguente mostra un corpo della richiesta che aggiunge un'organizzazione a un'applicazione IoT Central.

{
  "displayName": "Seattle",
}

Il corpo della richiesta include alcuni campi obbligatori:

  • @displayName: nome visualizzato dell'organizzazione.

Il corpo della richiesta include alcuni campi facoltativi:

  • @parent: ID dell'elemento padre dell'organizzazione.

Se non si specifica un elemento padre, l'organizzazione ottiene l'organizzazione di primo livello predefinita come padre.

La risposta a questa richiesta è simile all'esempio seguente:

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

È possibile creare un'organizzazione con gerarchia, ad esempio creare un'organizzazione di vendita con un'organizzazione padre.

L'esempio seguente mostra un corpo della richiesta che aggiunge un'organizzazione a un'applicazione IoT Central.

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

La risposta a questa richiesta è simile all'esempio seguente:

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

Ottenere un'organizzazione

Usare la richiesta seguente per recuperare i dettagli di una singola organizzazione dall'applicazione:

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

La risposta a questa richiesta è simile all'esempio seguente:

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

Aggiorna una organizzazione

Usare la richiesta seguente per aggiornare i dettagli di un'organizzazione nell'applicazione:

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

L'esempio seguente mostra un corpo della richiesta che aggiorna l'elemento padre dell'organizzazione:

{
  "parent": "washington"
}

La risposta a questa richiesta è simile all'esempio seguente:

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

Elencare le organizzazioni

Usare la richiesta seguente per recuperare un elenco di organizzazioni dall'applicazione:

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

La risposta a questa richiesta è simile all'esempio seguente.

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

Le organizzazioni Washington, Redmond e Bellevue hanno automaticamente l'organizzazione principale predefinita dell'applicazione come padre.

Elimina una organizzazione

Usare la richiesta seguente per eliminare un'organizzazione:

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

Usare le organizzazioni

Usare le organizzazioni per gestire l'accesso alle risorse nell'applicazione.

Gestire i ruoli

L'API REST consente di elencare i ruoli definiti nell'applicazione IoT Central. Usare la richiesta seguente per recuperare un elenco di ID ruolo applicazione e ruoli dell'organizzazione dall'applicazione. Per altre informazioni, vedere Come gestire le organizzazioni di IoT Central:

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

La risposta a questa richiesta è simile all'esempio seguente che include gli ID ruolo applicazione e ruolo organizzazione.

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

Creare un token API collegato a un nodo in una gerarchia dell'organizzazione

Usare la richiesta seguente per creare un token API collegato a un nodo in una gerarchia dell'organizzazione nell'applicazione:

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

L'esempio seguente mostra un corpo della richiesta che crea un token API per l'organizzazione seattle in un'applicazione IoT Central.

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

Il corpo della richiesta include alcuni campi obbligatori:

Nome Descrizione
ruolo ID di uno dei ruoli dell'organizzazione
organizzazione ID dell'organizzazione

La risposta a questa richiesta è simile all'esempio seguente:

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

Associare un utente a un nodo in una gerarchia dell'organizzazione

Usare la richiesta seguente per creare e associare un utente a un nodo in una gerarchia dell'organizzazione nell'applicazione. L'ID e il messaggio di posta elettronica devono essere univoci nell'applicazione:

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

Nel corpo della richiesta seguente, role è l'ID di uno dei ruoli dell'organizzazione e organization è l'ID dell'organizzazione

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

}

La risposta a questa richiesta è simile all'esempio seguente. Il valore del ruolo identifica il ruolo a cui è associato l'utente:

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

Aggiungere e associare un dispositivo a un'organizzazione

Usare la richiesta seguente per associare un nuovo dispositivo a un'organizzazione

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

L'esempio seguente mostra un corpo della richiesta che aggiunge un dispositivo per un modello di dispositivo. È possibile ottenere i template dettagli dalla pagina dei modelli di dispositivo nell'interfaccia utente dell'applicazione IoT Central.

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

Il corpo della richiesta include alcuni campi obbligatori:

  • @displayName: nome visualizzato del dispositivo.
  • @enabled: dichiara che questo oggetto è un'interfaccia.
  • @etag: ETag usato per evitare conflitti negli aggiornamenti del dispositivo.
  • simulated: il dispositivo è simulato?
  • template : definizione del modello di dispositivo per il dispositivo.
  • organizations : elenco di ID organizzazione di cui fa parte il dispositivo. Attualmente, è possibile associare un dispositivo solo a una singola organizzazione.

La risposta a questa richiesta è simile all'esempio seguente:

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

}

Aggiungere e associare un gruppo di dispositivi a un'organizzazione

Usare la richiesta seguente per creare e associare un nuovo gruppo di dispositivi a un'organizzazione.

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

Quando si crea un gruppo di dispositivi, si definisce un filter oggetto che seleziona i dispositivi da aggiungere al gruppo. Un filter oggetto identifica un modello di dispositivo e tutte le proprietà da associare. L'esempio seguente crea un gruppo di dispositivi che contiene tutti i dispositivi associati al dtmi:modelDefinition:dtdlv2 modello in cui la provisioned proprietà è true.

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

Il corpo della richiesta include alcuni campi obbligatori:

  • @displayName: nome visualizzato del gruppo di dispositivi.
  • @filter: query che definisce quali dispositivi devono trovarsi in questo gruppo.
  • description: breve riepilogo del gruppo di dispositivi.
  • organizations : elenco di ID organizzazione di cui fa parte il dispositivo. Attualmente, è possibile associare un dispositivo solo a una singola organizzazione.

La risposta a questa richiesta è simile all'esempio seguente:

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

Passaggi successivi

Ora che si è appreso come gestire le organizzazioni con l'API REST, un passaggio successivo consigliato consiste nell'usare l'API REST di IoT Central per gestire le esportazioni di dati.