Individual Enrollment - Create Or Update

Servizio:

IoT Hub Device Provisioning Service

Versione API:

2021-10-01

Create o aggiornare un record di registrazione del dispositivo.

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
id	path	True	string	Questo ID viene usato per identificare in modo univoco una registrazione del dispositivo di una registrazione. Stringa senza distinzione tra maiuscole e minuscole (fino a 128 caratteri lunghi) di caratteri alfanumerici e determinati caratteri speciali: . _ -. Nessun carattere speciale consentito all'inizio o alla fine.
api-version	query	True	string	Versione dell'API da usare per la richiesta. Le versioni supportate includono: 2021-10-01

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
If-Match		string	ETag del record di registrazione.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
attestation	True	AttestationMechanism	Meccanismo di attestazione per individualEnrollment e enrollmentGroup.
registrationId	True	string	Questo ID viene usato per identificare in modo univoco una registrazione del dispositivo di una registrazione. Stringa senza distinzione tra maiuscole e minuscole (fino a 128 caratteri) di caratteri alfanumerici più determinati caratteri speciali: . _ -. Nessun carattere speciale consentito all'inizio o alla fine.
allocationPolicy		enum: hashed geoLatency static custom	Criteri di allocazione di questa risorsa. Questo criterio esegue l'override dei criteri di allocazione a livello di tenant per questa singola registrazione o gruppo di registrazione. I valori possibili includono "hashed": gli hub IoT collegati sono altrettanto probabile che i dispositivi abbiano effettuato il provisioning, "geoLatenza" : i dispositivi vengono effettuato il provisioning in un hub IoT con la latenza più bassa del dispositivo. Se più hub IoT collegati forniscono la stessa latenza più bassa, il servizio di provisioning esegue l'hash dei dispositivi in tali hub, "statico" : specifica dell'hub IoT desiderato nell'elenco di registrazioni accetta la priorità sui criteri di allocazione a livello di servizio, 'custom': i dispositivi vengono distribuiti in un hub IoT basato sulla propria logica personalizzata. Il servizio di provisioning passa informazioni sul dispositivo alla logica e la logica restituisce l'hub IoT desiderato e la configurazione iniziale desiderata. È consigliabile usare Funzioni di Azure per ospitare la logica.
capabilities		DeviceCapabilities	Funzionalità del dispositivo.
customAllocationDefinition		CustomAllocationDefinition	Questo indica a DPS quale webhook chiamare quando si usa l'allocazione personalizzata.
deviceId		string	ID dispositivo desiderato hub IoT (facoltativo).
etag		string	Tag di entità associato alla risorsa.
initialTwin		InitialTwin	Dispositivo gemello iniziale. Contiene un subset delle proprietà di Twin.
iotHubHostName		string	Nome host dell'hub Iot.
iotHubs		string[]	L'elenco di hub IoT nomi host a cui è possibile allocare i dispositivi in questa risorsa. Deve essere un subset di elenco a livello di tenant degli hub IoT.
optionalDeviceInformation		TwinCollection	Rappresenta una raccolta di proprietà all'interno di un oggetto Twin
provisioningStatus		enum: enabled disabled	Stato del provisioning.
registrationState		DeviceRegistrationState	Stato di registrazione del dispositivo.
reprovisionPolicy		ReprovisionPolicy	Comportamento del servizio quando un dispositivo viene nuovamente eseguito il provisioning in un hub IoT.

Risposte

Nome	Tipo	Descrizione
200 OK	IndividualEnrollment	Operazione riuscita
Other Status Codes	ProvisioningServiceErrorDetails	Risposta di errore Intestazioni x-ms-error-code: string

Definizioni

Nome	Descrizione
AttestationMechanism	Meccanismo di attestazione per individualEnrollment e enrollmentGroup.
CustomAllocationDefinition	Indica al servizio Device Provisioning quale webhook chiamare quando si usa l'allocazione personalizzata.
DeviceCapabilities	Funzionalità del dispositivo.
DeviceRegistrationState	Stato di registrazione del dispositivo.
IndividualEnrollment	Record di registrazione del dispositivo.
InitialTwin	Dispositivo gemello iniziale. Contiene un subset delle proprietà di Twin.
InitialTwinProperties	Rappresenta le proprietà iniziali che verranno impostate nel dispositivo gemello.
Metadata	Metadati per TwinCollection
ProvisioningServiceErrorDetails	Contiene le proprietà di un errore restituito dal servizio di provisioning hub IoT di Azure.
ReprovisionPolicy	Comportamento del servizio quando viene eseguito di nuovo il provisioning di un dispositivo in un hub IoT.
SymmetricKeyAttestation	Attestazione tramite SymmetricKey.
TpmAttestation	Attestazione tramite TPM.
TwinCollection	Rappresenta una raccolta di proprietà all'interno di un oggetto Twin
X509Attestation	Attestazione tramite X509.
X509CAReferences	Riferimenti alla CA primaria e secondaria.
X509CertificateInfo	Informazioni sul certificato X509.
X509Certificates	Certificati primari e secondari
X509CertificateWithInfo	Informazioni su certificato e certificato

AttestationMechanism

Meccanismo di attestazione per individualEnrollment e enrollmentGroup.

Nome	Tipo	Descrizione
symmetricKey	SymmetricKeyAttestation	Attestazione tramite SymmetricKey.
tpm	TpmAttestation	Attestazione tramite TPM.
type	enum: none symmetricKey tpm x509	Tipo di attestazione.
x509	X509Attestation	Attestazione tramite X509.

CustomAllocationDefinition

Indica al servizio Device Provisioning quale webhook chiamare quando si usa l'allocazione personalizzata.

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

DeviceCapabilities

Funzionalità del dispositivo.

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

DeviceRegistrationState

Stato di registrazione del dispositivo.

Nome	Tipo	Descrizione
assignedHub	string	Assegnato hub IoT di Azure.
createdDateTimeUtc	string	La registrazione crea data e ora (in formato UTC).
deviceId	string	ID dispositivo.
errorCode	integer	Codice di errore.
errorMessage	string	Messaggio di errore.
etag	string	Tag di entità associato alla risorsa.
lastUpdatedDateTimeUtc	string	Data dell'ultimo aggiornamento (in formato UTC).
payload	object
registrationId	string	Questo ID viene usato per identificare in modo univoco una registrazione del dispositivo di una registrazione. Stringa senza distinzione tra maiuscole e minuscole (fino a 128 caratteri) di caratteri alfanumerici più determinati caratteri speciali: . _ -. Nessun carattere speciale consentito all'inizio o alla fine.
status	enum: assigned assigning disabled failed unassigned	Stato della registrazione.
substatus	enum: deviceDataMigrated deviceDataReset initialAssignment reprovisionedToInitialAssignment	Stato secondario per i dispositivi 'Assegnati'. I valori possibili includono : 'initialAssignment': il dispositivo è stato assegnato a un hub IoT per la prima volta, 'deviceDataMigrated': il dispositivo è stato assegnato a un hub IoT diverso e i relativi dati del dispositivo sono stati migrati dall'hub IoT assegnato in precedenza. I dati del dispositivo sono stati rimossi dall'hub IoT assegnato in precedenza, 'deviceDataReset': il dispositivo è stato assegnato a un hub IoT diverso e i relativi dati del dispositivo sono stati popolati dallo stato iniziale archiviato nella registrazione. I dati del dispositivo sono stati rimossi dall'hub IoT assegnato in precedenza, 'reprovisionedToInitialAssignment': è stato eseguito di nuovo il provisioning del dispositivo in un hub IoT assegnato in precedenza.

IndividualEnrollment

Record di registrazione del dispositivo.

Nome	Tipo	Valore predefinito	Descrizione
allocationPolicy	enum: custom geoLatency hashed static		Criteri di allocazione di questa risorsa. Questo criterio sostituisce i criteri di allocazione a livello di tenant per questa singola registrazione o gruppo di registrazione. I valori possibili includono "hashed": è probabile che gli hub IoT collegati dispongano di dispositivi di cui è stato effettuato il provisioning, ovvero "geoLatency": viene effettuato il provisioning dei dispositivi in un hub IoT con la latenza più bassa per il dispositivo. Se più hub IoT collegati forniscono la stessa latenza più bassa, il servizio di provisioning esegue l'hashing dei dispositivi in tali hub, "statico" : la specifica dell'hub IoT desiderato nell'elenco di registrazioni ha la priorità sui criteri di allocazione a livello di servizio, "custom": viene effettuato il provisioning dei dispositivi in un hub IoT basato sulla logica personalizzata. Il servizio di provisioning passa informazioni sul dispositivo alla logica e la logica restituisce l'hub IoT desiderato e la configurazione iniziale desiderata. È consigliabile usare Funzioni di Azure per ospitare la logica.
attestation	AttestationMechanism		Meccanismo di attestazione per individualEnrollment e enrollmentGroup.
capabilities	DeviceCapabilities		Funzionalità del dispositivo.
createdDateTimeUtc	string		Data/ora di creazione della risorsa.
customAllocationDefinition	CustomAllocationDefinition		Indica al servizio Device Provisioning quale webhook chiamare quando si usa l'allocazione personalizzata.
deviceId	string		ID dispositivo desiderato hub IoT (facoltativo).
etag	string		Tag di entità associato alla risorsa.
initialTwin	InitialTwin		Dispositivo gemello iniziale. Contiene un subset delle proprietà di Twin.
iotHubHostName	string		Nome host dell'hub Iot.
iotHubs	string[]		L'elenco di hub IoT nomi host a cui è possibile allocare i dispositivi in questa risorsa. Deve essere un subset di hub IoT a livello di tenant.
lastUpdatedDateTimeUtc	string		Data/ora dell'ultimo aggiornamento della risorsa.
optionalDeviceInformation	TwinCollection		Rappresenta una raccolta di proprietà all'interno di un oggetto Twin
provisioningStatus	enum: disabled enabled	enabled	Stato del provisioning.
registrationId	string		Questo ID viene usato per identificare in modo univoco una registrazione del dispositivo di una registrazione. Stringa senza distinzione tra maiuscole e minuscole (fino a 128 caratteri) di caratteri alfanumerici più determinati caratteri speciali: . _ -. Nessun carattere speciale consentito all'inizio o alla fine.
registrationState	DeviceRegistrationState		Stato di registrazione del dispositivo.
reprovisionPolicy	ReprovisionPolicy		Comportamento del servizio quando viene eseguito di nuovo il provisioning di un dispositivo in un hub IoT.

InitialTwin

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

Nome	Tipo	Descrizione
properties	InitialTwinProperties	Rappresenta le proprietà iniziali che verranno impostate nel dispositivo gemello.
tags	TwinCollection	Rappresenta una raccolta di proprietà all'interno di un oggetto Twin

InitialTwinProperties

Rappresenta le proprietà iniziali che verranno impostate nel dispositivo gemello.

Nome	Tipo	Descrizione
desired	TwinCollection	Rappresenta una raccolta di proprietà all'interno di un oggetto Twin

Metadata

Metadati per TwinCollection

Nome	Tipo	Descrizione
lastUpdated	string	Ora dell'ultimo aggiornamento di TwinCollection
lastUpdatedVersion	integer	Questo valore è Null per i metadati delle proprietà segnalate e non è Null per i metadati delle proprietà desiderati.

ProvisioningServiceErrorDetails

Contiene le proprietà di un errore restituito dal servizio di provisioning hub IoT di Azure.

Nome	Tipo	Descrizione
errorCode	integer
info	object
message	string
timestampUtc	string
trackingId	string

ReprovisionPolicy

Comportamento del servizio quando viene eseguito di nuovo il provisioning di un dispositivo in un hub IoT.

Nome	Tipo	Valore predefinito	Descrizione
migrateDeviceData	boolean	True	Se impostato su true (impostazione predefinita), il servizio Device Provisioning eseguirà la migrazione dei dati del dispositivo (funzionalità del dispositivo gemello, funzionalità del dispositivo e ID dispositivo) da un hub IoT a un altro durante un aggiornamento dell'assegnazione dell'hub IoT. Se impostato su false, il servizio Device Provisioning reimposta i dati del dispositivo sulla configurazione iniziale desiderata archiviata nell'elenco di registrazioni corrispondente.
updateHubAssignment	boolean	True	Se impostato su true (impostazione predefinita), il servizio Device Provisioning valuterà l'assegnazione hub IoT del dispositivo e la aggiornerà, se necessario, per eventuali richieste di provisioning oltre il primo da un determinato dispositivo. Se impostato su false, il dispositivo rimarrà assegnato all'hub IoT corrente.

SymmetricKeyAttestation

Attestazione tramite SymmetricKey.

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

TpmAttestation

Attestazione tramite TPM.

Nome	Tipo	Descrizione
endorsementKey	string
storageRootKey	string

TwinCollection

Rappresenta una raccolta di proprietà all'interno di un oggetto Twin

Nome	Tipo	Descrizione
count	integer	Numero di proprietà in TwinCollection
metadata	Metadata	Metadati per TwinCollection
version	integer	Versione di TwinCollection

X509Attestation

Attestazione tramite X509.

Nome	Tipo	Descrizione
caReferences	X509CAReferences	Riferimenti alla CA primaria e secondaria.
clientCertificates	X509Certificates	Certificati primari e secondari
signingCertificates	X509Certificates	Certificati primari e secondari

X509CAReferences

Riferimenti alla CA primaria e secondaria.

Nome	Tipo	Descrizione
primary	string
secondary	string

X509CertificateInfo

Informazioni sul certificato X509.

Nome	Tipo	Descrizione
issuerName	string
notAfterUtc	string
notBeforeUtc	string
serialNumber	string
sha1Thumbprint	string
sha256Thumbprint	string
subjectName	string
version	integer

X509Certificates

Certificati primari e secondari

Nome	Tipo	Descrizione
primary	X509CertificateWithInfo	Informazioni su certificato e certificato
secondary	X509CertificateWithInfo	Informazioni su certificato e certificato

X509CertificateWithInfo

Informazioni su certificato e certificato

Nome	Tipo	Descrizione
certificate	string
info	X509CertificateInfo	Informazioni sul certificato X509.