How to manage things with the registry

You use the AWS IoT console, AWS IoT API, or the AWS CLI to interact with the registry. The following sections show how to use the CLI to work with the registry.

When naming your thing objects:

• Don't use personally identifiable information in your thing name. The thing name can appear in unencrypted communications and reports.

Create a thing

The following command shows how to use the AWS IoT CreateThing command from the CLI to create a thing. You can't change a thing's name after you create it. To change a thing's name, create a new thing, give it the new name, and then delete the old thing.

$ aws iot create-thing --thing-name "MyLightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"

The CreateThing command displays the name and Amazon Resource Name (ARN) of your new thing:

{
    "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb",
    "thingName": "MyLightBulb",
    "thingId": "12345678abcdefgh12345678ijklmnop12345678"
}

Note

We don't recommend using personally identifiable information in your thing names.

For more information, see create-thing from the AWS CLI Command Reference.

List things

You can use the ListThings command to list all things in your account:

$ aws iot list-things

{
    "things": [
       {
            "attributes": {
                "model": "123",
                "wattage": "75"
            },
            "version": 1,
            "thingName": "MyLightBulb"
        },
        {
            "attributes": {
                "numOfStates":"3"
             },
            "version": 11,
            "thingName": "MyWallSwitch"
        }
    ]
}

You can use the ListThings command to search for all things of a specific thing type:

$  aws iot list-things --thing-type-name "LightBulb"

{
    "things": [
        {
            "thingTypeName": "LightBulb",
            "attributes": {
                "model": "123",
                "wattage": "75"
            },
            "version": 1,
            "thingName": "MyRGBLight"
        },
        {
            "thingTypeName": "LightBulb",
            "attributes": {
                "model": "123",
                "wattage": "75"
            },
            "version": 1,
            "thingName": "MySecondLightBulb"
        }
    ]
}

You can use the ListThings command to search for all things that have an attribute with a specific value. This command searches up to three attributes.

$  aws iot list-things --attribute-name "wattage" --attribute-value "75"

{
    "things": [
        {
            "thingTypeName": "StopLight",
            "attributes": {
                "model": "123",
                "wattage": "75"
            },
            "version": 3,
            "thingName": "MyLightBulb"
        },
        {
            "thingTypeName": "LightBulb",
            "attributes": {
                "model": "123",
                "wattage": "75"
            },
            "version": 1,
            "thingName": "MyRGBLight"
        },
        {
            "thingTypeName": "LightBulb",
            "attributes": {
                "model": "123",
                "wattage": "75"
            },
            "version": 1,
            "thingName": "MySecondLightBulb"
        }
    ]
}

For more information, see list-things from the AWS CLI Command Reference.

Describe things

You can use the DescribeThing command to display more detailed information about a thing:

$ aws iot describe-thing --thing-name "MyLightBulb"
{
    "version": 3,
    "thingName": "MyLightBulb",
    "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb",
    "thingId": "12345678abcdefgh12345678ijklmnop12345678",
    "defaultClientId": "MyLightBulb",
    "thingTypeName": "StopLight",
    "attributes": {
        "model": "123",
        "wattage": "75"
    }
}

For more information, see describe-thing from the AWS CLI Command Reference.

Update a thing

You can use the UpdateThing command to update a thing. This command updates only the thing's attributes. You can't change a thing's name. To change a thing's name, create a new thing, give it the new name, and then delete the old thing.

$ aws iot update-thing --thing-name "MyLightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"150\", \"model\":\"456\"}}"

The UpdateThing command does not produce output. You can use the DescribeThing command to see the result:

$ aws iot describe-thing --thing-name "MyLightBulb"
{
    "attributes": {
        "model": "456",
        "wattage": "150"
    },
    "version": 2,
    "thingName": "MyLightBulb"
}

For more information, see update-thing from the AWS CLI Command Reference.

Delete a thing

You can use the DeleteThing command to delete a thing:

$ aws iot delete-thing --thing-name "MyThing"

This command returns successfully with no error if the deletion is successful or you specify a thing that doesn't exist.

For more information, see delete-thing from the AWS CLI Command Reference.

Attach a principal to a thing

A physical device must have an X.509 certificate to communicate with AWS IoT. You can associate the certificate on your device with the thing in the registry that represents your device. To attach a certificate to your thing, use the AttachThingPrincipal command:

$ aws iot attach-thing-principal --thing-name "MyLightBulb" --principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"

The AttachThingPrincipal command does not produce any output.

For more information, see attach-thing-principal from the AWS CLI Command Reference.

Detach a principal from a thing

You can use the DetachThingPrincipal command to detach a certificate from a thing:

$ aws iot detach-thing-principal --thing-name "MyLightBulb" --principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"

The DetachThingPrincipal command doesn't produce any output.

For more information, see detach-thing-principal from the AWS CLI Command Reference.