thing_principals

Creates, updates, deletes, gets or lists a thing_principals resource.

Overview

Name	thing_principals
Type	Resource
Id	aws.iot.thing_principals

Fields

The following fields are returned by SELECT queries:

list_thing_principals

Name	Datatype	Description
principal	string	The principals associated with the thing.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_thing_principals	select	thing_name, region	nextToken, maxResults	Lists the principals associated with the specified thing. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities. Requires permission to access the ListThingPrincipals action.
attach_thing_principal	update	thing_name, x-amzn-principal, region	thingPrincipalType	Attaches the specified principal to the specified thing. A principal can be X.509 certificates, Amazon Cognito identities or federated identities. Requires permission to access the AttachThingPrincipal action.
detach_thing_principal	exec	thing_name, x-amzn-principal, region		Detaches the specified principal from the specified thing. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities. This call is asynchronous. It might take several seconds for the detachment to propagate. Requires permission to access the DetachThingPrincipal action.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)
thing_name	string	The name of the thing.
x-amzn-principal	string	If the principal is a certificate, this value must be ARN of the certificate. If the principal is an Amazon Cognito identity, this value must be the ID of the Amazon Cognito identity.
maxResults	integer	The maximum number of results to return in this operation.
nextToken	string	To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.
thingPrincipalType	string	The type of the relation you want to specify when you attach a principal to a thing. EXCLUSIVE_THING - Attaches the specified principal to the specified thing, exclusively. The thing will be the only thing that’s attached to the principal. NON_EXCLUSIVE_THING - Attaches the specified principal to the specified thing. Multiple things can be attached to the principal.

SELECT examples

list_thing_principals

Lists the principals associated with the specified thing. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities. Requires permission to access the ListThingPrincipals action.

SELECT
principal
FROM aws.iot.thing_principals
WHERE thing_name = '{{ thing_name }}' -- required
AND region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;

UPDATE examples

attach_thing_principal

Attaches the specified principal to the specified thing. A principal can be X.509 certificates, Amazon Cognito identities or federated identities. Requires permission to access the AttachThingPrincipal action.

UPDATE aws.iot.thing_principals
SET 
-- No updatable properties
WHERE 
thing_name = '{{ thing_name }}' --required
AND `x-amzn-principal` = '{{ x-amzn-principal }}' --required
AND region = '{{ region }}' --required
AND thingPrincipalType = '{{ thingPrincipalType}}';

Lifecycle Methods

detach_thing_principal

Detaches the specified principal from the specified thing. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities. This call is asynchronous. It might take several seconds for the detachment to propagate. Requires permission to access the DetachThingPrincipal action.

EXEC aws.iot.thing_principals.detach_thing_principal 
@thing_name='{{ thing_name }}' --required, 
@x-amzn-principal='{{ x-amzn-principal }}' --required, 
@region='{{ region }}' --required
;