Enrollment Group - Create Or Update

Servizio:: IoT Hub Device Provisioning Service

Versione API:: 2021-10-01

Crea o aggiorna un gruppo di registrazione dei dispositivi.

PUT https://{dpsName}.azure-devices-provisioning.net/enrollmentGroups/{id}?api-version=2021-10-01

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
dpsName	path	True	string	Il nome host dell'istanza DPS.
id	path	True	string	ID gruppo di registrazione.
api-version	query	True	string minLength: 1	Versione dell'API da usare per questa operazione.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
Authorization	True	string
If-Match		string	L'ETag del registro delle iscrizioni.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
attestation	True	AttestationMechanism	Metodo di attestazione utilizzato dal dispositivo.
enrollmentGroupId	True	string	ID del gruppo di iscrizione.
allocationPolicy		AllocationPolicy	La politica di allocazione di questa risorsa. Questa politica prevale sulla politica di allocazione a livello di inquilino per questo singolo iscrizione o gruppo di iscrizione. I valori possibili includono 'hashed': gli hub IoT collegati hanno la stessa probabilità di avere dispositivi provisionati su di loro, 'geoLatency': i dispositivi sono provisionati su un hub IoT con la latenza più bassa verso il dispositivo. Se più hub IoT collegati fornissero la stessa latenza più bassa, il servizio di provisioning hashizza i dispositivi su quegli hub, 'statico': la specifica dell'hub IoT desiderato nella lista di iscrizione ha priorità rispetto alla policy di allocazione per livello di servizio, 'personalizzata': i dispositivi sono provisionati su un hub IoT basandosi sulla tua logica personalizzata. Il servizio di provisioning passa informazioni sul dispositivo alla logica, che restituisce l'hub IoT desiderato così come la configurazione iniziale desiderata. Consigliamo di usare Azure Functions per ospitare la tua logica.
capabilities		DeviceCapabilities	Capacità del dispositivo.
customAllocationDefinition		CustomAllocationDefinition	Questo indica al DPS quale webhook chiamare quando si usa l'allocazione personalizzata.
etag		string	Il tag dell'entità associato alla risorsa.
initialTwin		InitialTwin	Dispositivo gemello iniziale.
iotHubHostName		string	Il nome host dell'Iot Hub.
iotHubs		string[]	L'elenco dei nomi host IoT Hub a cui il dispositivo o i dispositivi in questa risorsa può essere allocato. Deve essere un sottoinsieme della lista a livello di tenant degli hub IoT.
provisioningStatus		ProvisioningStatus	Lo stato di provisioning.
reprovisionPolicy		ReprovisionPolicy	Il comportamento quando un dispositivo viene rifornito su un hub IoT.

Risposte

Nome	Tipo	Descrizione
200 OK	EnrollmentGroup	La richiesta ha avuto esito positivo.
Other Status Codes	ProvisioningServiceErrorDetails	Risposta di errore imprevista. Intestazioni x-ms-error-code: string

Nome

Tipo

Descrizione

200 OK

EnrollmentGroup

La richiesta ha avuto esito positivo.

Other Status Codes

ProvisioningServiceErrorDetails

Risposta di errore imprevista.

Intestazioni

x-ms-error-code: string

Sicurezza

Authorization

Tipo: apiKey
In: header

Esempio

EnrollmentGroup_CreateOrUpdate_MaximumSet_Gen

EnrollmentGroup_CreateOrUpdate_MinimumSet_Gen

EnrollmentGroup_CreateOrUpdate_MaximumSet_Gen

Esempio di richiesta

HTTP

PUT https://{dpsName}.azure-devices-provisioning.net/enrollmentGroups/qhukjjfosohaiywmmbxxhanzyhz?api-version=2021-10-01


{
  "allocationPolicy": "hashed",
  "attestation": {
    "type": "none",
    "symmetricKey": {
      "primaryKey": "tdoshkmlo",
      "secondaryKey": "lmajoyzuojahffcmdlcwjhntqzyqzk"
    },
    "tpm": {
      "endorsementKey": "naoofgjbxiulcitlysusxdvagyucgn",
      "storageRootKey": "tdgkgcvptrsw"
    },
    "x509": {
      "caReferences": {
        "primary": "efbkbboxkvrsdl",
        "secondary": "vckhuzqgbcinighxwyuyd"
      },
      "clientCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      },
      "signingCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      }
    }
  },
  "capabilities": {
    "iotEdge": true
  },
  "customAllocationDefinition": {
    "apiVersion": "gbannxdstouqrfonxdxfurv",
    "webhookUrl": "todqbubyxeumrtvhsscedwrkz"
  },
  "enrollmentGroupId": "sfsevlobqfdnqmghunj",
  "etag": "kmvtdrkjyfzj",
  "initialTwin": {
    "properties": {
      "desired": {
        "count": 16,
        "key2428": {},
        "metadata": {
          "lastUpdated": "2025-10-01T17:42:04.76Z",
          "lastUpdatedVersion": 19
        },
        "version": 9
      }
    },
    "tags": {
      "count": 16,
      "key2428": {},
      "metadata": {
        "lastUpdated": "2025-10-01T17:42:04.76Z",
        "lastUpdatedVersion": 19
      },
      "version": 9
    }
  },
  "iotHubHostName": "dey",
  "iotHubs": [
    "ehqilokxpijrvaigiaf"
  ],
  "provisioningStatus": "enabled",
  "reprovisionPolicy": {
    "migrateDeviceData": true,
    "updateHubAssignment": true
  }
}

Risposta di esempio

Codice di stato:: 200

{
  "allocationPolicy": "hashed",
  "attestation": {
    "type": "none",
    "symmetricKey": {
      "primaryKey": "tdoshkmlo",
      "secondaryKey": "lmajoyzuojahffcmdlcwjhntqzyqzk"
    },
    "tpm": {
      "endorsementKey": "naoofgjbxiulcitlysusxdvagyucgn",
      "storageRootKey": "tdgkgcvptrsw"
    },
    "x509": {
      "caReferences": {
        "primary": "efbkbboxkvrsdl",
        "secondary": "vckhuzqgbcinighxwyuyd"
      },
      "clientCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      },
      "signingCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      }
    }
  },
  "capabilities": {
    "iotEdge": true
  },
  "createdDateTimeUtc": "2025-10-01T17:42:05.495Z",
  "customAllocationDefinition": {
    "apiVersion": "gbannxdstouqrfonxdxfurv",
    "webhookUrl": "todqbubyxeumrtvhsscedwrkz"
  },
  "enrollmentGroupId": "sfsevlobqfdnqmghunj",
  "etag": "kmvtdrkjyfzj",
  "initialTwin": {
    "properties": {
      "desired": {
        "count": 16,
        "key2428": {},
        "metadata": {
          "lastUpdated": "2025-10-01T17:42:04.76Z",
          "lastUpdatedVersion": 19
        },
        "version": 9
      }
    },
    "tags": {
      "count": 16,
      "key2428": {},
      "metadata": {
        "lastUpdated": "2025-10-01T17:42:04.76Z",
        "lastUpdatedVersion": 19
      },
      "version": 9
    }
  },
  "iotHubHostName": "dey",
  "iotHubs": [
    "ehqilokxpijrvaigiaf"
  ],
  "lastUpdatedDateTimeUtc": "2025-10-01T17:42:05.495Z",
  "provisioningStatus": "enabled",
  "reprovisionPolicy": {
    "migrateDeviceData": true,
    "updateHubAssignment": true
  }
}

EnrollmentGroup_CreateOrUpdate_MinimumSet_Gen

Esempio di richiesta

HTTP

PUT https://{dpsName}.azure-devices-provisioning.net/enrollmentGroups/dqxvwdvxnofungqfi?api-version=2021-10-01

{
  "attestation": {
    "type": "none"
  },
  "enrollmentGroupId": "sfsevlobqfdnqmghunj"
}

Risposta di esempio

Codice di stato:: 200

{
  "attestation": {
    "type": "none"
  },
  "enrollmentGroupId": "sfsevlobqfdnqmghunj"
}

Definizioni

Nome	Descrizione
AllocationPolicy	La politica di allocazione di questa risorsa. Questa politica prevale sulla politica di allocazione a livello di inquilino per questo singolo iscrizione o gruppo di iscrizione. I valori possibili includono 'hashed': gli hub IoT collegati hanno la stessa probabilità di avere dispositivi provisionati su di loro, 'geoLatency': i dispositivi sono provisionati su un hub IoT con la latenza più bassa verso il dispositivo. Se più hub IoT collegati fornissero la stessa latenza più bassa, il servizio di provisioning hashizza i dispositivi su quegli hub, 'statico': la specifica dell'hub IoT desiderato nella lista di iscrizione ha priorità rispetto alla policy di allocazione per livello di servizio, 'personalizzata': i dispositivi sono provisionati su un hub IoT basandosi sulla tua logica personalizzata. Il servizio di provisioning passa informazioni sul dispositivo alla logica, che restituisce l'hub IoT desiderato così come la configurazione iniziale desiderata. Consigliamo di usare Azure Functions per ospitare la tua logica.
AttestationMechanism	Meccanismo di attestazione per l'iscrizione individuale e per il gruppo di iscrizione.
AttestationType	Tipo di attestazione.
CustomAllocationDefinition	Questo indica al DPS quale webhook chiamare quando si usa l'allocazione personalizzata.
DeviceCapabilities	Capacità del dispositivo.
EnrollmentGroup	Registro del gruppo di iscrizione.
InitialTwin	Dispositivo gemello iniziale. Contiene un sottoinsieme delle proprietà di Twin.
InitialTwinProperties	Rappresenta le proprietà iniziali che saranno impostate sul gemello del dispositivo.
Metadata	Metadati per la TwinCollection
ProvisioningServiceErrorDetails	Contiene le proprietà di un errore restituito dall'Azure IoT Hub Provisioning Service.
ProvisioningStatus	Lo stato di provisioning.
ReprovisionPolicy	Il comportamento del servizio quando un dispositivo viene ri-provisionato su un hub IoT.
SymmetricKeyAttestation	Attestazione tramite SymmetricKey.
TpmAttestation	Attestazione tramite TPM.
TwinCollection	Rappresenta una raccolta di proprietà all'interno di un Gemello
X509Attestation	Attestazione tramite X509.
X509CAReferences	Referenze CA primarie e secondarie.
X509CertificateInfo	Informazioni sul certificato X509.
X509Certificates	Certificati primari e secondari
X509CertificateWithInfo	Certificati e informazioni sui certificati

AllocationPolicy

Enumerazione

La politica di allocazione di questa risorsa. Questa politica prevale sulla politica di allocazione a livello di inquilino per questo singolo iscrizione o gruppo di iscrizione. I valori possibili includono 'hashed': gli hub IoT collegati hanno la stessa probabilità di avere dispositivi provisionati su di loro, 'geoLatency': i dispositivi sono provisionati su un hub IoT con la latenza più bassa verso il dispositivo. Se più hub IoT collegati fornissero la stessa latenza più bassa, il servizio di provisioning hashizza i dispositivi su quegli hub, 'statico': la specifica dell'hub IoT desiderato nella lista di iscrizione ha priorità rispetto alla policy di allocazione per livello di servizio, 'personalizzata': i dispositivi sono provisionati su un hub IoT basandosi sulla tua logica personalizzata. Il servizio di provisioning passa informazioni sul dispositivo alla logica, che restituisce l'hub IoT desiderato così come la configurazione iniziale desiderata. Consigliamo di usare Azure Functions per ospitare la tua logica.

Valore	Descrizione
hashed	hash
geoLatency	geoLatency
static	statico
custom	custom

AttestationMechanism

Oggetto

Meccanismo di attestazione per l'iscrizione individuale e per il gruppo di iscrizione.

Nome	Tipo	Descrizione
symmetricKey	SymmetricKeyAttestation	Metodo di attestazione simmetrica della chiave.
tpm	TpmAttestation	Metodo di attestazione TPM.
type	AttestationType	Tipo di attestazione.
x509	X509Attestation	Metodo di attestazione X509.

AttestationType

Enumerazione

Tipo di attestazione.

Valore	Descrizione
none	nessuno
tpm	tpm
x509	x509
symmetricKey	symmetricKey

CustomAllocationDefinition

Oggetto

Questo indica al DPS quale webhook chiamare quando si usa l'allocazione personalizzata.

Nome	Tipo	Descrizione
apiVersion	string	La versione API dei tipi di servizio di provisioning (come IndividualEnrollment) inviata nella richiesta di allocazione personalizzata. Versione minima supportata: "2018-09-01-preview".
webhookUrl	string	L'URL del webhook utilizzato per le richieste di allocazione.

DeviceCapabilities

Oggetto

Capacità del dispositivo.

Nome	Tipo	Valore predefinito	Descrizione
iotEdge	boolean	False	Se impostato su true, questo dispositivo è un dispositivo IoTEdge.

EnrollmentGroup

Oggetto

Registro del gruppo di iscrizione.

Nome	Tipo	Valore predefinito	Descrizione
allocationPolicy	AllocationPolicy		La politica di allocazione di questa risorsa. Questa politica prevale sulla politica di allocazione a livello di inquilino per questo singolo iscrizione o gruppo di iscrizione. I valori possibili includono 'hashed': gli hub IoT collegati hanno la stessa probabilità di avere dispositivi provisionati su di loro, 'geoLatency': i dispositivi sono provisionati su un hub IoT con la latenza più bassa verso il dispositivo. Se più hub IoT collegati fornissero la stessa latenza più bassa, il servizio di provisioning hashizza i dispositivi su quegli hub, 'statico': la specifica dell'hub IoT desiderato nella lista di iscrizione ha priorità rispetto alla policy di allocazione per livello di servizio, 'personalizzata': i dispositivi sono provisionati su un hub IoT basandosi sulla tua logica personalizzata. Il servizio di provisioning passa informazioni sul dispositivo alla logica, che restituisce l'hub IoT desiderato così come la configurazione iniziale desiderata. Consigliamo di usare Azure Functions per ospitare la tua logica.
attestation	AttestationMechanism		Metodo di attestazione utilizzato dal dispositivo.
capabilities	DeviceCapabilities		Capacità del dispositivo.
createdDateTimeUtc	string (date-time)		La DateTime è stata creata questa risorsa.
customAllocationDefinition	CustomAllocationDefinition		Questo indica al DPS quale webhook chiamare quando si usa l'allocazione personalizzata.
enrollmentGroupId	string		ID del gruppo di iscrizione.
etag	string		Il tag dell'entità associato alla risorsa.
initialTwin	InitialTwin		Dispositivo gemello iniziale.
iotHubHostName	string		Il nome host dell'Iot Hub.
iotHubs	string[]		L'elenco dei nomi host IoT Hub a cui il dispositivo o i dispositivi in questa risorsa può essere allocato. Deve essere un sottoinsieme della lista a livello di tenant degli hub IoT.
lastUpdatedDateTimeUtc	string (date-time)		La DateTime di questa risorsa è stata aggiornata l'ultima volta.
provisioningStatus	ProvisioningStatus	enabled	Lo stato di provisioning.
reprovisionPolicy	ReprovisionPolicy		Il comportamento quando un dispositivo viene rifornito su un hub IoT.

InitialTwin

Oggetto

Dispositivo gemello iniziale. Contiene un sottoinsieme delle proprietà di Twin.

Nome	Tipo	Descrizione
properties	InitialTwinProperties	Proprietà desiderate del dispositivo gemello.
tags	TwinCollection	Tag gemelli.

InitialTwinProperties

Oggetto

Rappresenta le proprietà iniziali che saranno impostate sul gemello del dispositivo.

Nome	Tipo	Descrizione
desired	TwinCollection	Ottiene e imposta le proprietà desiderate da InitialTwin.

Metadata

Oggetto

Metadati per la TwinCollection

Nome	Tipo	Descrizione
lastUpdated	string (date-time)	L'ultima volta che la TwinCollection è stata aggiornata
lastUpdatedVersion	integer (int32)	Questo è nullo per i metadati delle proprietà riportate e non è nullo per i metadati delle proprietà desiderate.

ProvisioningServiceErrorDetails

Oggetto

Contiene le proprietà di un errore restituito dall'Azure IoT Hub Provisioning Service.

Nome	Tipo	Descrizione
errorCode	integer (int32)	Codice di errore per l'operazione.
info	object	Dizionario di <stringa>
message	string	Messaggio di errore leggibile dall'uomo.
timestampUtc	string (date-time)	Ora UTC dell'errore.
trackingId	string	ID di tracciamento per l'errore.

ProvisioningStatus

Enumerazione

Lo stato di provisioning.

Valore	Descrizione
enabled	enabled
disabled	disattivato

ReprovisionPolicy

Oggetto

Il comportamento del servizio quando un dispositivo viene ri-provisionato su un hub IoT.

Nome	Tipo	Valore predefinito	Descrizione
migrateDeviceData	boolean	True	Quando impostato su true (predefinito), il Device Provisioning Service migrerà i dati del dispositivo (gemelli, capacità del dispositivo e ID dispositivo) da un hub IoT all'altro durante un aggiornamento di assegnazione dell'hub IoT. Se impostato su falso, il Servizio di Provisioning del Dispositivo resetterà i dati del dispositivo alla configurazione iniziale desiderata memorizzata nella corrispondente lista di iscrizione.
updateHubAssignment	boolean	True	Quando impostato su true (predefinito), il Device Provisioning Service valuterà l'assegnazione dell'IoT Hub del dispositivo e la aggiornerà se necessario per eventuali richieste di provisioning oltre la prima da parte di un determinato dispositivo. Se impostato su falso, il dispositivo rimarrà assegnato al suo attuale hub IoT.

SymmetricKeyAttestation

Oggetto

Attestazione tramite SymmetricKey.

Nome	Tipo	Descrizione
primaryKey	string	Chiave simmetrica primaria.
secondaryKey	string	Chiave simmetrica secondaria.

TpmAttestation

Oggetto

Attestazione tramite TPM.

Nome	Tipo	Descrizione
endorsementKey	string	Chiave per l'endorsement di TPM.
storageRootKey	string	Chiave radice di archiviazione TPM.

TwinCollection

Oggetto

Rappresenta una raccolta di proprietà all'interno di un Gemello

Nome	Tipo	Descrizione
count	integer (int32)	Numero di proprietà nella TwinCollection
metadata	Metadata	Metadati per la TwinCollection
version	integer (int32)	Versione della TwinCollection

X509Attestation

Oggetto

Attestazione tramite X509.

Nome	Tipo	Descrizione
caReferences	X509CAReferences	Referenze CA primarie e secondarie.
clientCertificates	X509Certificates	Certificati primari e secondari
signingCertificates	X509Certificates	Certificati primari e secondari

X509CAReferences

Oggetto

Referenze CA primarie e secondarie.

Nome	Tipo	Descrizione
primary	string	Riferimento principale della CA.
secondary	string	Riferimento secondario per la CA.

X509CertificateInfo

Oggetto

Informazioni sul certificato X509.

Nome	Tipo	Descrizione
issuerName	string	Nome dell'emittente del certificato.
notAfterUtc	string (date-time)	Fine della validità del certificato (UTC).
notBeforeUtc	string (date-time)	Inizio validità del certificato (UTC).
serialNumber	string	Numero di serie del certificato.
sha1Thumbprint	string	Impronta digitale SHA-1 del certificato.
sha256Thumbprint	string	Impronta digitale SHA-256 del certificato.
subjectName	string	Nome soggetto del certificato.
version	integer (int32)	Versione del certificato.

X509Certificates

Oggetto

Certificati primari e secondari

Nome	Tipo	Descrizione
primary	X509CertificateWithInfo	Certificati e informazioni sui certificati
secondary	X509CertificateWithInfo	Certificati e informazioni sui certificati

X509CertificateWithInfo

Oggetto

Certificati e informazioni sui certificati

Nome	Tipo	Descrizione
certificate	string	Stringa di certificati formattata in PEM.
info	X509CertificateInfo	Informazioni sul certificato X509.