future = getAsyncClient().attachThingPrincipal(principalRequest);
future.whenComplete((attachResponse, ex) -> {
if (attachResponse != null && attachResponse.sdkHttpResponse().isSuccessful()) {
System.out.println("Certificate attached to Thing successfully.");
// Print additional information about the Thing.
describeThing(thingName);
} else {
Throwable cause = ex != null ? ex.getCause() : null;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else if (cause != null) {
System.err.println("Unexpected error: " + cause.getMessage());
} else {
System.err.println("Failed to attach certificate to Thing. HTTP Status Code: " +
attachResponse.sdkHttpResponse().statusCode());
}
}
});
future.join();
}
```
+ For API details, see [AttachThingPrincipal](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/AttachThingPrincipal) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun attachCertificateToThing(
thingNameVal: String?,
certificateArn: String?,
) {
val principalRequest =
AttachThingPrincipalRequest {
thingName = thingNameVal
principal = certificateArn
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
iotClient.attachThingPrincipal(principalRequest)
println("Certificate attached to $thingNameVal successfully.")
}
}
```
+ For API details, see [AttachThingPrincipal](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def attach_thing_principal(self, thing_name, principal):
"""
Attaches a certificate to an AWS IoT thing.
:param thing_name: The name of the thing.
:param principal: The ARN of the certificate.
"""
try:
self.iot_client.attach_thing_principal(
thingName=thing_name, principal=principal
)
logger.info("Attached principal %s to thing %s.", principal, thing_name)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceNotFoundException":
logger.error("Cannot attach principal. Resource not found.")
return
logger.error(
"Couldn't attach principal to thing. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [AttachThingPrincipal](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/AttachThingPrincipal) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `CreateKeysAndCertificate` with an AWS SDK or CLI
The following code examples show how to use `CreateKeysAndCertificate`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
+ [Getting started with IoT Core](iot_example_iot_GettingStarted_063_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Creates a device certificate for AWS IoT.
///
/// The certificate details including ARN and certificate PEM, or null if creation failed.
public async Task<(string CertificateArn, string CertificatePem, string CertificateId)?> CreateKeysAndCertificateAsync()
{
try
{
var request = new CreateKeysAndCertificateRequest
{
SetAsActive = true
};
var response = await _amazonIoT.CreateKeysAndCertificateAsync(request);
_logger.LogInformation($"Created certificate with ARN {response.CertificateArn}");
return (response.CertificateArn, response.CertificatePem, response.CertificateId);
}
catch (Amazon.IoT.Model.ThrottlingException ex)
{
_logger.LogWarning($"Request throttled, please try again later: {ex.Message}");
return null;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't create certificate. Here's why: {ex.Message}");
return null;
}
}
```
+ For API details, see [CreateKeysAndCertificate](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/CreateKeysAndCertificate) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Create keys and certificate for an Aws IoT device.
//! This routine will save certificates and keys to an output folder, if provided.
/*!
\param outputFolder: Location for storing output in files, ignored when string is empty.
\param certificateARNResult: A string to receive the ARN of the created certificate.
\param certificateID: A string to receive the ID of the created certificate.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::createKeysAndCertificate(const Aws::String &outputFolder,
Aws::String &certificateARNResult,
Aws::String &certificateID,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient client(clientConfiguration);
Aws::IoT::Model::CreateKeysAndCertificateRequest createKeysAndCertificateRequest;
Aws::IoT::Model::CreateKeysAndCertificateOutcome outcome =
client.CreateKeysAndCertificate(createKeysAndCertificateRequest);
if (outcome.IsSuccess()) {
std::cout << "Successfully created a certificate and keys" << std::endl;
certificateARNResult = outcome.GetResult().GetCertificateArn();
certificateID = outcome.GetResult().GetCertificateId();
std::cout << "Certificate ARN: " << certificateARNResult << ", certificate ID: "
<< certificateID << std::endl;
if (!outputFolder.empty()) {
std::cout << "Writing certificate and keys to the folder '" << outputFolder
<< "'." << std::endl;
std::cout << "Be sure these files are stored securely." << std::endl;
Aws::String certificateFilePath = outputFolder + "/certificate.pem.crt";
std::ofstream certificateFile(certificateFilePath);
if (!certificateFile.is_open()) {
std::cerr << "Error opening certificate file, '" << certificateFilePath
<< "'."
<< std::endl;
return false;
}
certificateFile << outcome.GetResult().GetCertificatePem();
certificateFile.close();
const Aws::IoT::Model::KeyPair &keyPair = outcome.GetResult().GetKeyPair();
Aws::String privateKeyFilePath = outputFolder + "/private.pem.key";
std::ofstream privateKeyFile(privateKeyFilePath);
if (!privateKeyFile.is_open()) {
std::cerr << "Error opening private key file, '" << privateKeyFilePath
<< "'."
<< std::endl;
return false;
}
privateKeyFile << keyPair.GetPrivateKey();
privateKeyFile.close();
Aws::String publicKeyFilePath = outputFolder + "/public.pem.key";
std::ofstream publicKeyFile(publicKeyFilePath);
if (!publicKeyFile.is_open()) {
std::cerr << "Error opening public key file, '" << publicKeyFilePath
<< "'."
<< std::endl;
return false;
}
publicKeyFile << keyPair.GetPublicKey();
}
}
else {
std::cerr << "Error creating keys and certificate: "
<< outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [CreateKeysAndCertificate](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/CreateKeysAndCertificate) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To create an RSA key pair and issue an X.509 certificate**
The following `create-keys-and-certificate` creates a 2048-bit RSA key pair and issues an X.509 certificate using the issued public key. Because this is the only time that AWS IoT provides the private key for this certificate, be sure to keep it in a secure location.
```
aws iot create-keys-and-certificate \
--certificate-pem-outfile "myTest.cert.pem" \
--public-key-outfile "myTest.public.key" \
--private-key-outfile "myTest.private.key"
```
Output:
```
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/9894ba17925e663f1d29c23af4582b8e3b7619c31f3fbd93adcb51ae54b83dc2",
"certificateId": "9894ba17925e663f1d29c23af4582b8e3b7619c31f3fbd93adcb51ae54b83dc2",
"certificatePem": "
-----BEGIN CERTIFICATE-----
MIICiTCCEXAMPLE6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgEXAMPLEAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSEXAMPLE2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYEXAMPLEb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCEXAMPLEJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDAEXAMPLEsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEXAMPLE25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+aEXAMPLE
EXAMPLEfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZEXAMPLELG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAEXAMPLEWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9qEXAMPLEyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDEXAMPLEBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE=
-----END CERTIFICATE-----\n",
"keyPair": {
"PublicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkEXAMPLEQEFAAOCAQ8AMIIBCgKCAQEAEXAMPLE1nnyJwKSMHw4h\nMMEXAMPLEuuN/dMAS3fyce8DW/4+EXAMPLEyjmoF/YVF/gHr99VEEXAMPLE5VF13\n59VK7cEXAMPLE67GK+y+jikqXOgHh/xJTwo+sGpWEXAMPLEDz18xOd2ka4tCzuWEXAMPLEahJbYkCPUBSU8opVkR7qkEXAMPLE1DR6sx2HocliOOLtu6Fkw91swQWEXAMPLE\GB3ZPrNh0PzQYvjUStZeccyNCx2EXAMPLEvp9mQOUXP6plfgxwKRX2fEXAMPLEDa\nhJLXkX3rHU2xbxJSq7D+XEXAMPLEcw+LyFhI5mgFRl88eGdsAEXAMPLElnI9EesG\nFQIDAQAB\n-----END PUBLIC KEY-----\n",
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nkey omittted for security reasons\n-----END RSA PRIVATE KEY-----\n"
}
}
```
For more information, see [Create and Register an AWS IoT Device Certificate](https://docs.aws.amazon.com/iot/latest/developerguide/device-certs-create.html) in the **AWS IoT Developer Guide**.
+ For API details, see [CreateKeysAndCertificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-keys-and-certificate.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Creates an IoT certificate asynchronously.
*
* @return The ARN of the created certificate.
*
* This method initiates an asynchronous request to create an IoT certificate.
* If the request is successful, it prints the certificate details and returns the certificate ARN.
* If an exception occurs, it prints the error message.
*/
public String createCertificate() {
CompletableFuture future = getAsyncClient().createKeysAndCertificate();
final String[] certificateArn = {null};
future.whenComplete((response, ex) -> {
if (response != null) {
String certificatePem = response.certificatePem();
certificateArn[0] = response.certificateArn();
// Print the details.
System.out.println("\nCertificate:");
System.out.println(certificatePem);
System.out.println("\nCertificate ARN:");
System.out.println(certificateArn[0]);
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else {
System.err.println("Unexpected error: " + cause.getMessage());
}
}
});
future.join();
return certificateArn[0];
}
```
+ For API details, see [CreateKeysAndCertificate](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/CreateKeysAndCertificate) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun createCertificate(): String? {
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
val response = iotClient.createKeysAndCertificate()
val certificatePem = response.certificatePem
val certificateArn = response.certificateArn
// Print the details.
println("\nCertificate:")
println(certificatePem)
println("\nCertificate ARN:")
println(certificateArn)
return certificateArn
}
}
```
+ For API details, see [CreateKeysAndCertificate](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def create_keys_and_certificate(self):
"""
Creates keys and a certificate for an AWS IoT thing.
:return: The certificate ID, ARN, and PEM.
"""
try:
response = self.iot_client.create_keys_and_certificate(setAsActive=True)
logger.info("Created certificate %s.", response["certificateId"])
except ClientError as err:
if err.response["Error"]["Code"] == "ThrottlingException":
logger.error("Request throttled. Please try again later.")
else:
logger.error(
"Couldn't create keys and certificate. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ For API details, see [CreateKeysAndCertificate](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/CreateKeysAndCertificate) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `CreateThing` with an AWS SDK or CLI
The following code examples show how to use `CreateThing`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
+ [Getting started with IoT Core](iot_example_iot_GettingStarted_063_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Creates an AWS IoT Thing.
///
/// The name of the Thing to create.
/// The ARN of the Thing created, or null if creation failed.
public async Task CreateThingAsync(string thingName)
{
try
{
var request = new CreateThingRequest
{
ThingName = thingName
};
var response = await _amazonIoT.CreateThingAsync(request);
_logger.LogInformation($"Created Thing {thingName} with ARN {response.ThingArn}");
return response.ThingArn;
}
catch (Amazon.IoT.Model.ResourceAlreadyExistsException ex)
{
_logger.LogWarning($"Thing {thingName} already exists: {ex.Message}");
return null;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't create Thing {thingName}. Here's why: {ex.Message}");
return null;
}
}
```
+ For API details, see [CreateThing](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/CreateThing) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Create an AWS IoT thing.
/*!
\param thingName: The name for the thing.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::createThing(const Aws::String &thingName,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::CreateThingRequest createThingRequest;
createThingRequest.SetThingName(thingName);
Aws::IoT::Model::CreateThingOutcome outcome = iotClient.CreateThing(
createThingRequest);
if (outcome.IsSuccess()) {
std::cout << "Successfully created thing " << thingName << std::endl;
}
else {
std::cerr << "Failed to create thing " << thingName << ": " <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [CreateThing](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/CreateThing) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To create a thing record in the registry**
The following `create-thing` example creates an entry for a device in the AWS IoT thing registry.
```
aws iot create-thing \
--thing-name SampleIoTThing
```
Output:
```
{
"thingName": "SampleIoTThing",
"thingArn": "arn:aws:iot:us-west-2: 123456789012:thing/SampleIoTThing",
"thingId": " EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE "
}
```
**Example 2: To define a thing that is associated with a thing type**
The following `create-thing` example create a thing that has the specified thing type and its attributes.
```
aws iot create-thing \
--thing-name "MyLightBulb" \
--thing-type-name "LightBulb" \
--attribute-payload "{"attributes": {"wattage":"75", "model":"123"}}"
```
Output:
```
{
"thingName": "MyLightBulb",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyLightBulb",
"thingId": "40da2e73-c6af-406e-b415-15acae538797"
}
```
For more information, see [How to Manage Things with the Registry](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html) and [Thing Types](https://docs.aws.amazon.com/iot/latest/developerguide/thing-types.html) in the *AWS IoT Developers Guide*.
+ For API details, see [CreateThing](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-thing.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Creates an IoT Thing with the specified name asynchronously.
*
* @param thingName The name of the IoT Thing to create.
*
* This method initiates an asynchronous request to create an IoT Thing with the specified name.
* If the request is successful, it prints the name of the thing and its ARN value.
* If an exception occurs, it prints the error message.
*/
public void createIoTThing(String thingName) {
CreateThingRequest createThingRequest = CreateThingRequest.builder()
.thingName(thingName)
.build();
CompletableFuture future = getAsyncClient().createThing(createThingRequest);
future.whenComplete((createThingResponse, ex) -> {
if (createThingResponse != null) {
System.out.println(thingName + " was successfully created. The ARN value is " + createThingResponse.thingArn());
} else {
Throwable cause = ex.getCause();
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else {
System.err.println("Unexpected error: " + cause.getMessage());
}
}
});
future.join();
}
```
+ For API details, see [CreateThing](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/CreateThing) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun createIoTThing(thingNameVal: String) {
val createThingRequest =
CreateThingRequest {
thingName = thingNameVal
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
iotClient.createThing(createThingRequest)
println("Created $thingNameVal}")
}
}
```
+ For API details, see [CreateThing](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def create_thing(self, thing_name):
"""
Creates an AWS IoT thing.
:param thing_name: The name of the thing to create.
:return: The name and ARN of the created thing.
"""
try:
response = self.iot_client.create_thing(thingName=thing_name)
logger.info("Created thing %s.", thing_name)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceAlreadyExistsException":
logger.info("Thing %s already exists. Skipping creation.", thing_name)
return None
logger.error(
"Couldn't create thing %s. Here's why: %s: %s",
thing_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response
```
+ For API details, see [CreateThing](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/CreateThing) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `CreateTopicRule` with an AWS SDK or CLI
The following code examples show how to use `CreateTopicRule`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Creates an IoT topic rule.
///
/// The name of the rule.
/// The ARN of the SNS topic for the action.
/// The ARN of the IAM role.
/// True if successful, false otherwise.
public async Task CreateTopicRuleAsync(string ruleName, string snsTopicArn, string roleArn)
{
try
{
var request = new CreateTopicRuleRequest
{
RuleName = ruleName,
TopicRulePayload = new TopicRulePayload
{
Sql = "SELECT * FROM 'topic/subtopic'",
Description = $"Rule created by .NET example: {ruleName}",
Actions = new List
{
new Amazon.IoT.Model.Action
{
Sns = new SnsAction
{
TargetArn = snsTopicArn,
RoleArn = roleArn
}
}
},
RuleDisabled = false
}
};
await _amazonIoT.CreateTopicRuleAsync(request);
_logger.LogInformation($"Created IoT rule {ruleName}");
return true;
}
catch (Amazon.IoT.Model.ResourceAlreadyExistsException ex)
{
_logger.LogWarning($"Rule {ruleName} already exists: {ex.Message}");
return false;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't create topic rule. Here's why: {ex.Message}");
return false;
}
}
```
+ For API details, see [CreateTopicRule](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/CreateTopicRule) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Create an AWS IoT rule with an SNS topic as the target.
/*!
\param ruleName: The name for the rule.
\param snsTopic: The SNS topic ARN for the action.
\param sql: The SQL statement used to query the topic.
\param roleARN: The IAM role ARN for the action.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool
AwsDoc::IoT::createTopicRule(const Aws::String &ruleName,
const Aws::String &snsTopicARN, const Aws::String &sql,
const Aws::String &roleARN,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::CreateTopicRuleRequest request;
request.SetRuleName(ruleName);
Aws::IoT::Model::SnsAction snsAction;
snsAction.SetTargetArn(snsTopicARN);
snsAction.SetRoleArn(roleARN);
Aws::IoT::Model::Action action;
action.SetSns(snsAction);
Aws::IoT::Model::TopicRulePayload topicRulePayload;
topicRulePayload.SetSql(sql);
topicRulePayload.SetActions({action});
request.SetTopicRulePayload(topicRulePayload);
auto outcome = iotClient.CreateTopicRule(request);
if (outcome.IsSuccess()) {
std::cout << "Successfully created topic rule " << ruleName << "." << std::endl;
}
else {
std::cerr << "Error creating topic rule " << ruleName << ": " <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [CreateTopicRule](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/CreateTopicRule) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To create a rule that sends an Amazon SNS alert**
The following `create-topic-rule` example creates a rule that sends an Amazon SNS message when soil moisture level readings, as found in a device shadow, are low.
```
aws iot create-topic-rule \
--rule-name "LowMoistureRule" \
--topic-rule-payload file://plant-rule.json
```
The example requires the following JSON code to be saved to a file named `plant-rule.json`:
```
{
"sql": "SELECT * FROM '$aws/things/MyRPi/shadow/update/accepted' WHERE state.reported.moisture = 'low'\n",
"description": "Sends an alert whenever soil moisture level readings are too low.",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [{
"sns": {
"targetArn": "arn:aws:sns:us-west-2:123456789012:MyRPiLowMoistureTopic",
"roleArn": "arn:aws:iam::123456789012:role/service-role/MyRPiLowMoistureTopicRole",
"messageFormat": "RAW"
}
}]
}
```
This command produces no output.
For more information, see [Creating an AWS IoT Rule](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-rule.html) in the *AWS IoT Developers Guide*.
+ For API details, see [CreateTopicRule](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-topic-rule.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Creates an IoT rule asynchronously.
*
* @param roleARN The ARN of the IAM role that grants access to the rule's actions.
* @param ruleName The name of the IoT rule.
* @param action The ARN of the action to perform when the rule is triggered.
*
* This method initiates an asynchronous request to create an IoT rule.
* If the request is successful, it prints a confirmation message.
* If an exception occurs, it prints the error message.
*/
public void createIoTRule(String roleARN, String ruleName, String action) {
String sql = "SELECT * FROM '" + TOPIC + "'";
SnsAction action1 = SnsAction.builder()
.targetArn(action)
.roleArn(roleARN)
.build();
// Create the action.
Action myAction = Action.builder()
.sns(action1)
.build();
// Create the topic rule payload.
TopicRulePayload topicRulePayload = TopicRulePayload.builder()
.sql(sql)
.actions(myAction)
.build();
// Create the topic rule request.
CreateTopicRuleRequest topicRuleRequest = CreateTopicRuleRequest.builder()
.ruleName(ruleName)
.topicRulePayload(topicRulePayload)
.build();
CompletableFuture future = getAsyncClient().createTopicRule(topicRuleRequest);
future.whenComplete((response, ex) -> {
if (response != null) {
System.out.println("IoT Rule created successfully.");
} else {
Throwable cause = ex != null ? ex.getCause() : null;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else if (cause != null) {
System.err.println("Unexpected error: " + cause.getMessage());
} else {
System.err.println("Failed to create IoT Rule.");
}
}
});
future.join();
}
```
+ For API details, see [CreateTopicRule](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/CreateTopicRule) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun createIoTRule(
roleARNVal: String?,
ruleNameVal: String?,
action: String?,
) {
val sqlVal = "SELECT * FROM '$TOPIC '"
val action1 =
SnsAction {
targetArn = action
roleArn = roleARNVal
}
val myAction =
Action {
sns = action1
}
val topicRulePayloadVal =
TopicRulePayload {
sql = sqlVal
actions = listOf(myAction)
}
val topicRuleRequest =
CreateTopicRuleRequest {
ruleName = ruleNameVal
topicRulePayload = topicRulePayloadVal
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
iotClient.createTopicRule(topicRuleRequest)
println("IoT rule created successfully.")
}
}
```
+ For API details, see [CreateTopicRule](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def create_topic_rule(self, rule_name, topic, sns_action_arn, role_arn):
"""
Creates an AWS IoT topic rule.
:param rule_name: The name of the rule.
:param topic: The MQTT topic to subscribe to.
:param sns_action_arn: The ARN of the SNS topic to publish to.
:param role_arn: The ARN of the IAM role.
"""
try:
self.iot_client.create_topic_rule(
ruleName=rule_name,
topicRulePayload={
"sql": f"SELECT * FROM '{topic}'",
"actions": [
{"sns": {"targetArn": sns_action_arn, "roleArn": role_arn}}
],
},
)
logger.info("Created topic rule %s.", rule_name)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceAlreadyExistsException":
logger.info("Topic rule %s already exists. Skipping creation.", rule_name)
return
logger.error(
"Couldn't create topic rule. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [CreateTopicRule](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/CreateTopicRule) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `DeleteCertificate` with an AWS SDK or CLI
The following code examples show how to use `DeleteCertificate`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
+ [Getting started with IoT Core](iot_example_iot_GettingStarted_063_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Deletes an IoT certificate.
///
/// The ID of the certificate to delete.
/// True if successful, false otherwise.
public async Task DeleteCertificateAsync(string certificateId)
{
try
{
// First, update the certificate to inactive state
var updateRequest = new UpdateCertificateRequest
{
CertificateId = certificateId,
NewStatus = CertificateStatus.INACTIVE
};
await _amazonIoT.UpdateCertificateAsync(updateRequest);
// Then delete the certificate
var deleteRequest = new DeleteCertificateRequest
{
CertificateId = certificateId
};
await _amazonIoT.DeleteCertificateAsync(deleteRequest);
_logger.LogInformation($"Deleted certificate {certificateId}");
return true;
}
catch (Amazon.IoT.Model.ResourceNotFoundException ex)
{
_logger.LogError($"Cannot delete certificate - resource not found: {ex.Message}");
return false;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't delete certificate. Here's why: {ex.Message}");
return false;
}
}
```
+ For API details, see [DeleteCertificate](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/DeleteCertificate) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Delete a certificate.
/*!
\param certificateID: The ID of a certificate.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::deleteCertificate(const Aws::String &certificateID,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::DeleteCertificateRequest request;
request.SetCertificateId(certificateID);
Aws::IoT::Model::DeleteCertificateOutcome outcome = iotClient.DeleteCertificate(
request);
if (outcome.IsSuccess()) {
std::cout << "Successfully deleted certificate " << certificateID << std::endl;
}
else {
std::cerr << "Error deleting certificate " << certificateID << ": " <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [DeleteCertificate](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/DeleteCertificate) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To delete a device certificate**
The following `delete-certificate` example deletes the device certificate with the specified ID.
```
aws iot delete-certificate \
--certificate-id c0c57bbc8baaf4631a9a0345c957657f5e710473e3ddbee1428d216d54d53ac9
```
This command produces no output.
For more information, see [DeleteCertificate](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCertificate.html) in the *AWS IoT API Reference*.
+ For API details, see [DeleteCertificate](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/delete-certificate.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Deletes a certificate asynchronously.
*
* @param certificateArn The ARN of the certificate to delete.
*
* This method initiates an asynchronous request to delete a certificate.
* If the deletion is successful, it prints a confirmation message.
* If an exception occurs, it prints the error message.
*/
public void deleteCertificate(String certificateArn) {
DeleteCertificateRequest certificateProviderRequest = DeleteCertificateRequest.builder()
.certificateId(extractCertificateId(certificateArn))
.build();
CompletableFuture future = getAsyncClient().deleteCertificate(certificateProviderRequest);
future.whenComplete((voidResult, ex) -> {
if (ex == null) {
System.out.println(certificateArn + " was successfully deleted.");
} else {
Throwable cause = ex.getCause();
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else {
System.err.println("Unexpected error: " + ex.getMessage());
}
}
});
future.join();
}
```
+ For API details, see [DeleteCertificate](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/DeleteCertificate) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun deleteCertificate(certificateArn: String) {
val certificateProviderRequest =
DeleteCertificateRequest {
certificateId = extractCertificateId(certificateArn)
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
iotClient.deleteCertificate(certificateProviderRequest)
println("$certificateArn was successfully deleted.")
}
}
```
+ For API details, see [DeleteCertificate](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def delete_certificate(self, certificate_id):
"""
Deletes an AWS IoT certificate.
:param certificate_id: The ID of the certificate to delete.
"""
try:
self.iot_client.update_certificate(
certificateId=certificate_id, newStatus="INACTIVE"
)
self.iot_client.delete_certificate(certificateId=certificate_id)
logger.info("Deleted certificate %s.", certificate_id)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceNotFoundException":
logger.error("Cannot delete certificate. Resource not found.")
return
logger.error(
"Couldn't delete certificate. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DeleteCertificate](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/DeleteCertificate) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `DeleteThing` with an AWS SDK or CLI
The following code examples show how to use `DeleteThing`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
+ [Getting started with IoT Core](iot_example_iot_GettingStarted_063_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Deletes an IoT Thing.
///
/// The name of the Thing to delete.
/// True if successful, false otherwise.
public async Task DeleteThingAsync(string thingName)
{
try
{
var request = new DeleteThingRequest
{
ThingName = thingName
};
await _amazonIoT.DeleteThingAsync(request);
_logger.LogInformation($"Deleted Thing {thingName}");
return true;
}
catch (Amazon.IoT.Model.ResourceNotFoundException ex)
{
_logger.LogError($"Cannot delete Thing - resource not found: {ex.Message}");
return false;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't delete Thing. Here's why: {ex.Message}");
return false;
}
}
```
+ For API details, see [DeleteThing](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/DeleteThing) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Delete an AWS IoT thing.
/*!
\param thingName: The name for the thing.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::deleteThing(const Aws::String &thingName,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::DeleteThingRequest request;
request.SetThingName(thingName);
const auto outcome = iotClient.DeleteThing(request);
if (outcome.IsSuccess()) {
std::cout << "Successfully deleted thing " << thingName << std::endl;
}
else {
std::cerr << "Error deleting thing " << thingName << ": " <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [DeleteThing](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/DeleteThing) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To display detailed information about a thing**
The following `delete-thing` example deletes a thing from the AWS IoT registry for your AWS account.
aws iot delete-thing --thing-name "FourthBulb"
This command produces no output.
For more information, see [How to Manage Things with the Registry](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html) in the *AWS IoT Developers Guide*.
+ For API details, see [DeleteThing](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/delete-thing.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Deletes an IoT Thing asynchronously.
*
* @param thingName The name of the IoT Thing to delete.
*
* This method initiates an asynchronous request to delete an IoT Thing.
* If the deletion is successful, it prints a confirmation message.
* If an exception occurs, it prints the error message.
*/
public void deleteIoTThing(String thingName) {
DeleteThingRequest deleteThingRequest = DeleteThingRequest.builder()
.thingName(thingName)
.build();
CompletableFuture future = getAsyncClient().deleteThing(deleteThingRequest);
future.whenComplete((voidResult, ex) -> {
if (ex == null) {
System.out.println("Deleted Thing " + thingName);
} else {
Throwable cause = ex.getCause();
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else {
System.err.println("Unexpected error: " + ex.getMessage());
}
}
});
future.join();
}
```
+ For API details, see [DeleteThing](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/DeleteThing) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun deleteIoTThing(thingNameVal: String) {
val deleteThingRequest =
DeleteThingRequest {
thingName = thingNameVal
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
iotClient.deleteThing(deleteThingRequest)
println("Deleted $thingNameVal")
}
}
```
+ For API details, see [DeleteThing](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def delete_thing(self, thing_name):
"""
Deletes an AWS IoT thing.
:param thing_name: The name of the thing to delete.
"""
try:
self.iot_client.delete_thing(thingName=thing_name)
logger.info("Deleted thing %s.", thing_name)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceNotFoundException":
logger.error("Cannot delete thing. Resource not found.")
return
logger.error(
"Couldn't delete thing. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DeleteThing](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/DeleteThing) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `DeleteTopicRule` with an AWS SDK or CLI
The following code examples show how to use `DeleteTopicRule`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Delete an AWS IoT rule.
/*!
\param ruleName: The name for the rule.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::deleteTopicRule(const Aws::String &ruleName,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::DeleteTopicRuleRequest request;
request.SetRuleName(ruleName);
Aws::IoT::Model::DeleteTopicRuleOutcome outcome = iotClient.DeleteTopicRule(
request);
if (outcome.IsSuccess()) {
std::cout << "Successfully deleted rule " << ruleName << std::endl;
}
else {
std::cerr << "Failed to delete rule " << ruleName <<
": " << outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [DeleteTopicRule](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/DeleteTopicRule) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To delete a rule**
The following `delete-topic-rule` example deletes the specified rule.
```
aws iot delete-topic-rule \
--rule-name "LowMoistureRule"
```
This command produces no output.
For more information, see [Deleting a Rule](https://docs.aws.amazon.com/iot/latest/developerguide/iot-delete-rule.html) in the *AWS IoT Developers Guide*.
+ For API details, see [DeleteTopicRule](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/delete-topic-rule.html) in *AWS CLI Command Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def delete_topic_rule(self, rule_name):
"""
Deletes an AWS IoT topic rule.
:param rule_name: The name of the rule to delete.
"""
try:
self.iot_client.delete_topic_rule(ruleName=rule_name)
logger.info("Deleted topic rule %s.", rule_name)
except ClientError as err:
logger.error(
"Couldn't delete topic rule. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DeleteTopicRule](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/DeleteTopicRule) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `DescribeEndpoint` with an AWS SDK or CLI
The following code examples show how to use `DescribeEndpoint`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
+ [Getting started with IoT Core](iot_example_iot_GettingStarted_063_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Gets the AWS IoT endpoint URL.
///
/// The endpoint URL, or null if retrieval failed.
public async Task DescribeEndpointAsync()
{
try
{
var request = new DescribeEndpointRequest
{
EndpointType = "iot:Data-ATS"
};
var response = await _amazonIoT.DescribeEndpointAsync(request);
_logger.LogInformation($"Retrieved endpoint: {response.EndpointAddress}");
return response.EndpointAddress;
}
catch (Amazon.IoT.Model.ThrottlingException ex)
{
_logger.LogWarning($"Request throttled, please try again later: {ex.Message}");
return null;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't describe endpoint. Here's why: {ex.Message}");
return null;
}
}
```
+ For API details, see [DescribeEndpoint](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/DescribeEndpoint) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Describe the endpoint specific to the AWS account making the call.
/*!
\param endpointResult: String to receive the endpoint result.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::describeEndpoint(Aws::String &endpointResult,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::String endpoint;
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::DescribeEndpointRequest describeEndpointRequest;
describeEndpointRequest.SetEndpointType(
"iot:Data-ATS"); // Recommended endpoint type.
Aws::IoT::Model::DescribeEndpointOutcome outcome = iotClient.DescribeEndpoint(
describeEndpointRequest);
if (outcome.IsSuccess()) {
std::cout << "Successfully described endpoint." << std::endl;
endpointResult = outcome.GetResult().GetEndpointAddress();
}
else {
std::cerr << "Error describing endpoint" << outcome.GetError().GetMessage()
<< std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [DescribeEndpoint](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/DescribeEndpoint) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get your current AWS endpoint**
The following `describe-endpoint` example retrieves the default AWS endpoint to which all commands are applied.
```
aws iot describe-endpoint
```
Output:
```
{
"endpointAddress": "abc123defghijk.iot.us-west-2.amazonaws.com"
}
```
For more information, see [DescribeEndpoint](https://docs.aws.amazon.com/iot/latest/developerguide/iot-commands.html#api-iot-DescribeEndpoint) in the *AWS IoT Developer Guide*.
**Example 2: To get your ATS endpoint**
The following `describe-endpoint` example retrieves the Amazon Trust Services (ATS) endpoint.
```
aws iot describe-endpoint \
--endpoint-type iot:Data-ATS
```
Output:
```
{
"endpointAddress": "abc123defghijk-ats.iot.us-west-2.amazonaws.com"
}
```
For more information, see [X.509 Certificates and AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/managing-device-certs.html) in the *AWS IoT Developer Guide*.
+ For API details, see [DescribeEndpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-endpoint.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Describes the endpoint of the IoT service asynchronously.
*
* @return A CompletableFuture containing the full endpoint URL.
*
* This method initiates an asynchronous request to describe the endpoint of the IoT service.
* If the request is successful, it prints and returns the full endpoint URL.
* If an exception occurs, it prints the error message.
*/
public String describeEndpoint() {
CompletableFuture future = getAsyncClient().describeEndpoint(DescribeEndpointRequest.builder().endpointType("iot:Data-ATS").build());
final String[] result = {null};
future.whenComplete((endpointResponse, ex) -> {
if (endpointResponse != null) {
String endpointUrl = endpointResponse.endpointAddress();
String exString = getValue(endpointUrl);
String fullEndpoint = "https://" + exString + "-ats.iot.us-east-1.amazonaws.com";
System.out.println("Full Endpoint URL: " + fullEndpoint);
result[0] = fullEndpoint;
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else {
System.err.println("Unexpected error: " + cause.getMessage());
}
}
});
future.join();
return result[0];
}
```
+ For API details, see [DescribeEndpoint](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/DescribeEndpoint) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun describeEndpoint(): String? {
val request = DescribeEndpointRequest {}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
val endpointResponse = iotClient.describeEndpoint(request)
val endpointUrl: String? = endpointResponse.endpointAddress
val exString: String = getValue(endpointUrl)
val fullEndpoint = "https://$exString-ats.iot.us-east-1.amazonaws.com"
println("Full endpoint URL: $fullEndpoint")
return fullEndpoint
}
}
```
+ For API details, see [DescribeEndpoint](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def describe_endpoint(self, endpoint_type="iot:Data-ATS"):
"""
Gets the AWS IoT endpoint.
:param endpoint_type: The endpoint type.
:return: The endpoint.
"""
try:
response = self.iot_client.describe_endpoint(endpointType=endpoint_type)
logger.info("Retrieved endpoint %s.", response["endpointAddress"])
except ClientError as err:
if err.response["Error"]["Code"] == "ThrottlingException":
logger.error("Request throttled. Please try again later.")
else:
logger.error(
"Couldn't describe endpoint. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["endpointAddress"]
```
+ For API details, see [DescribeEndpoint](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/DescribeEndpoint) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/iot#code-examples).
```
async fn show_address(client: &Client, endpoint_type: &str) -> Result<(), Error> {
let resp = client
.describe_endpoint()
.endpoint_type(endpoint_type)
.send()
.await?;
println!("Endpoint address: {}", resp.endpoint_address.unwrap());
println!();
Ok(())
}
```
+ For API details, see [DescribeEndpoint](https://docs.rs/aws-sdk-iot/latest/aws_sdk_iot/client/struct.Client.html#method.describe_endpoint) in *AWS SDK for Rust API reference*.
------
# Use `DescribeThing` with an AWS SDK or CLI
The following code examples show how to use `DescribeThing`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Describe an AWS IoT thing.
/*!
\param thingName: The name for the thing.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::describeThing(const Aws::String &thingName,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::DescribeThingRequest request;
request.SetThingName(thingName);
Aws::IoT::Model::DescribeThingOutcome outcome = iotClient.DescribeThing(request);
if (outcome.IsSuccess()) {
const Aws::IoT::Model::DescribeThingResult &result = outcome.GetResult();
std::cout << "Retrieved thing '" << result.GetThingName() << "'" << std::endl;
std::cout << "thingArn: " << result.GetThingArn() << std::endl;
std::cout << result.GetAttributes().size() << " attribute(s) retrieved"
<< std::endl;
for (const auto &attribute: result.GetAttributes()) {
std::cout << " attribute: " << attribute.first << "=" << attribute.second
<< std::endl;
}
}
else {
std::cerr << "Error describing thing " << thingName << ": " <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [DescribeThing](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/DescribeThing) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To display detailed information about a thing**
The following `describe-thing` example display information about a thing (device) that is defined in the AWS IoT registry for your AWS account.
aws iot describe-thing --thing-name "MyLightBulb"
Output:
```
{
"defaultClientId": "MyLightBulb",
"thingName": "MyLightBulb",
"thingId": "40da2e73-c6af-406e-b415-15acae538797",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyLightBulb",
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1
}
```
For more information, see [How to Manage Things with the Registry](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html) in the *AWS IoT Developers Guide*.
+ For API details, see [DescribeThing](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/describe-thing.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Describes an IoT Thing asynchronously.
*
* @param thingName The name of the IoT Thing.
*
* This method initiates an asynchronous request to describe an IoT Thing.
* If the request is successful, it prints the Thing details.
* If an exception occurs, it prints the error message.
*/
private void describeThing(String thingName) {
DescribeThingRequest thingRequest = DescribeThingRequest.builder()
.thingName(thingName)
.build();
CompletableFuture future = getAsyncClient().describeThing(thingRequest);
future.whenComplete((describeResponse, ex) -> {
if (describeResponse != null) {
System.out.println("Thing Details:");
System.out.println("Thing Name: " + describeResponse.thingName());
System.out.println("Thing ARN: " + describeResponse.thingArn());
} else {
Throwable cause = ex != null ? ex.getCause() : null;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else if (cause != null) {
System.err.println("Unexpected error: " + cause.getMessage());
} else {
System.err.println("Failed to describe Thing.");
}
}
});
future.join();
}
```
+ For API details, see [DescribeThing](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/DescribeThing) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun describeThing(thingNameVal: String) {
val thingRequest =
DescribeThingRequest {
thingName = thingNameVal
}
// Print Thing details.
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
val describeResponse = iotClient.describeThing(thingRequest)
println("Thing details:")
println("Thing name: ${describeResponse.thingName}")
println("Thing ARN: ${describeResponse.thingArn}")
}
}
```
+ For API details, see [DescribeThing](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
# Use `DetachThingPrincipal` with an AWS SDK or CLI
The following code examples show how to use `DetachThingPrincipal`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
+ [Getting started with IoT Core](iot_example_iot_GettingStarted_063_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Detaches a certificate from an IoT Thing.
///
/// The name of the Thing.
/// The ARN of the certificate to detach.
/// True if successful, false otherwise.
public async Task DetachThingPrincipalAsync(string thingName, string certificateArn)
{
try
{
var request = new DetachThingPrincipalRequest
{
ThingName = thingName,
Principal = certificateArn
};
await _amazonIoT.DetachThingPrincipalAsync(request);
_logger.LogInformation($"Detached certificate {certificateArn} from Thing {thingName}");
return true;
}
catch (Amazon.IoT.Model.ResourceNotFoundException ex)
{
_logger.LogError($"Cannot detach certificate - resource not found: {ex.Message}");
return false;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't detach certificate from Thing. Here's why: {ex.Message}");
return false;
}
}
```
+ For API details, see [DetachThingPrincipal](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/DetachThingPrincipal) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Detach a principal from an AWS IoT thing.
/*!
\param principal: A principal to detach.
\param thingName: The name for the thing.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::detachThingPrincipal(const Aws::String &principal,
const Aws::String &thingName,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::DetachThingPrincipalRequest detachThingPrincipalRequest;
detachThingPrincipalRequest.SetThingName(thingName);
detachThingPrincipalRequest.SetPrincipal(principal);
Aws::IoT::Model::DetachThingPrincipalOutcome outcome = iotClient.DetachThingPrincipal(
detachThingPrincipalRequest);
if (outcome.IsSuccess()) {
std::cout << "Successfully detached principal " << principal << " from thing "
<< thingName << std::endl;
}
else {
std::cerr << "Failed to detach principal " << principal << " from thing "
<< thingName << ": "
<< outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [DetachThingPrincipal](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/DetachThingPrincipal) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To detach a certificate/principal from a thing**
The following `detach-thing-principal` example removes a certificate that represents a principal from the specified thing.
```
aws iot detach-thing-principal \
--thing-name "MyLightBulb" \
--principal "arn:aws:iot:us-west-2:123456789012:cert/604c48437a57b7d5fc5d137c5be75011c6ee67c9a6943683a1acb4b1626bac36"
```
This command produces no output.
For more information, see [How to Manage Things with the Registry](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html) in the *AWS IoT Developers Guide*.
+ For API details, see [DetachThingPrincipal](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/detach-thing-principal.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Detaches a principal (certificate) from an IoT Thing asynchronously.
*
* @param thingName The name of the IoT Thing.
* @param certificateArn The ARN of the certificate to detach.
*
* This method initiates an asynchronous request to detach a certificate from an IoT Thing.
* If the detachment is successful, it prints a confirmation message.
* If an exception occurs, it prints the error message.
*/
public void detachThingPrincipal(String thingName, String certificateArn) {
DetachThingPrincipalRequest thingPrincipalRequest = DetachThingPrincipalRequest.builder()
.principal(certificateArn)
.thingName(thingName)
.build();
CompletableFuture future = getAsyncClient().detachThingPrincipal(thingPrincipalRequest);
future.whenComplete((voidResult, ex) -> {
if (ex == null) {
System.out.println(certificateArn + " was successfully removed from " + thingName);
} else {
Throwable cause = ex.getCause();
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else {
System.err.println("Unexpected error: " + ex.getMessage());
}
}
});
future.join();
}
```
+ For API details, see [DetachThingPrincipal](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/DetachThingPrincipal) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun detachThingPrincipal(
thingNameVal: String,
certificateArn: String,
) {
val thingPrincipalRequest =
DetachThingPrincipalRequest {
principal = certificateArn
thingName = thingNameVal
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
iotClient.detachThingPrincipal(thingPrincipalRequest)
println("$certificateArn was successfully removed from $thingNameVal")
}
}
```
+ For API details, see [DetachThingPrincipal](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def detach_thing_principal(self, thing_name, principal):
"""
Detaches a certificate from an AWS IoT thing.
:param thing_name: The name of the thing.
:param principal: The ARN of the certificate.
"""
try:
self.iot_client.detach_thing_principal(
thingName=thing_name, principal=principal
)
logger.info("Detached principal %s from thing %s.", principal, thing_name)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceNotFoundException":
logger.error("Cannot detach principal. Resource not found.")
return
logger.error(
"Couldn't detach principal from thing. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DetachThingPrincipal](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/DetachThingPrincipal) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `ListCertificates` with an AWS SDK or CLI
The following code examples show how to use `ListCertificates`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Lists all certificates associated with the account.
///
/// List of certificate information, or empty list if listing failed.
public async Task> ListCertificatesAsync()
{
try
{
var request = new ListCertificatesRequest();
var response = await _amazonIoT.ListCertificatesAsync(request);
_logger.LogInformation($"Retrieved {response.Certificates.Count} certificates");
return response.Certificates;
}
catch (Amazon.IoT.Model.ThrottlingException ex)
{
_logger.LogWarning($"Request throttled, please try again later: {ex.Message}");
return new List();
}
catch (Exception ex)
{
_logger.LogError($"Couldn't list certificates. Here's why: {ex.Message}");
return new List();
}
}
```
+ For API details, see [ListCertificates](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/ListCertificates) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! List certificates registered in the AWS account making the call.
/*!
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::listCertificates(
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::ListCertificatesRequest request;
Aws::Vector allCertificates;
Aws::String marker; // Used to paginate results.
do {
if (!marker.empty()) {
request.SetMarker(marker);
}
Aws::IoT::Model::ListCertificatesOutcome outcome = iotClient.ListCertificates(
request);
if (outcome.IsSuccess()) {
const Aws::IoT::Model::ListCertificatesResult &result = outcome.GetResult();
marker = result.GetNextMarker();
allCertificates.insert(allCertificates.end(),
result.GetCertificates().begin(),
result.GetCertificates().end());
}
else {
std::cerr << "Error: " << outcome.GetError().GetMessage() << std::endl;
return false;
}
} while (!marker.empty());
std::cout << allCertificates.size() << " certificate(s) found." << std::endl;
for (auto &certificate: allCertificates) {
std::cout << "Certificate ID: " << certificate.GetCertificateId() << std::endl;
std::cout << "Certificate ARN: " << certificate.GetCertificateArn()
<< std::endl;
std::cout << std::endl;
}
return true;
}
```
+ For API details, see [ListCertificates](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/ListCertificates) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list the certificates registered in your AWS account**
The following `list-certificates` example lists all certificates registered in your account. If you have more than the default paging limit of 25, you can use the `nextMarker` response value from this command and supply it to the next command to get the next batch of results. Repeat until `nextMarker` returns without a value.
```
aws iot list-certificates
```
Output:
```
{
"certificates": [
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/604c48437a57b7d5fc5d137c5be75011c6ee67c9a6943683a1acb4b1626bac36",
"certificateId": "604c48437a57b7d5fc5d137c5be75011c6ee67c9a6943683a1acb4b1626bac36",
"status": "ACTIVE",
"creationDate": 1556810537.617
},
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/262a1ac8a7d8aa72f6e96e365480f7313aa9db74b8339ec65d34dc3074e1c31e",
"certificateId": "262a1ac8a7d8aa72f6e96e365480f7313aa9db74b8339ec65d34dc3074e1c31e",
"status": "ACTIVE",
"creationDate": 1546447050.885
},
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/b193ab7162c0fadca83246d24fa090300a1236fe58137e121b011804d8ac1d6b",
"certificateId": "b193ab7162c0fadca83246d24fa090300a1236fe58137e121b011804d8ac1d6b",
"status": "ACTIVE",
"creationDate": 1546292258.322
},
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/7aebeea3845d14a44ec80b06b8b78a89f3f8a706974b8b34d18f5adf0741db42",
"certificateId": "7aebeea3845d14a44ec80b06b8b78a89f3f8a706974b8b34d18f5adf0741db42",
"status": "ACTIVE",
"creationDate": 1541457693.453
},
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/54458aa39ebb3eb39c91ffbbdcc3a6ca1c7c094d1644b889f735a6fc2cd9a7e3",
"certificateId": "54458aa39ebb3eb39c91ffbbdcc3a6ca1c7c094d1644b889f735a6fc2cd9a7e3",
"status": "ACTIVE",
"creationDate": 1541113568.611
},
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/4f0ba725787aa94d67d2fca420eca022242532e8b3c58e7465c7778b443fd65e",
"certificateId": "4f0ba725787aa94d67d2fca420eca022242532e8b3c58e7465c7778b443fd65e",
"status": "ACTIVE",
"creationDate": 1541022751.983
}
]
}
```
+ For API details, see [ListCertificates](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-certificates.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Lists all certificates asynchronously.
*
* This method initiates an asynchronous request to list all certificates.
* If the request is successful, it prints the certificate IDs and ARNs.
* If an exception occurs, it prints the error message.
*/
public void listCertificates() {
CompletableFuture future = getAsyncClient().listCertificates();
future.whenComplete((response, ex) -> {
if (response != null) {
List certList = response.certificates();
for (Certificate cert : certList) {
System.out.println("Cert id: " + cert.certificateId());
System.out.println("Cert Arn: " + cert.certificateArn());
}
} else {
Throwable cause = ex != null ? ex.getCause() : null;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else if (cause != null) {
System.err.println("Unexpected error: " + cause.getMessage());
} else {
System.err.println("Failed to list certificates.");
}
}
});
future.join();
}
```
+ For API details, see [ListCertificates](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/ListCertificates) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun listCertificates() {
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
val response = iotClient.listCertificates()
val certList = response.certificates
certList?.forEach { cert ->
println("Cert id: ${cert.certificateId}")
println("Cert Arn: ${cert.certificateArn}")
}
}
}
```
+ For API details, see [ListCertificates](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def list_certificates(self):
"""
Lists AWS IoT certificates.
:return: The list of certificates.
"""
try:
certificates = []
paginator = self.iot_client.get_paginator("list_certificates")
for page in paginator.paginate():
certificates.extend(page["certificates"])
logger.info("Retrieved %s certificates.", len(certificates))
return certificates
except ClientError as err:
if err.response["Error"]["Code"] == "ThrottlingException":
logger.error("Request throttled. Please try again later.")
else:
logger.error(
"Couldn't list certificates. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [ListCertificates](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/ListCertificates) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `ListThings` with an AWS SDK or CLI
The following code examples show how to use `ListThings`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Lists IoT Things with pagination support.
///
/// List of Things, or empty list if listing failed.
public async Task> ListThingsAsync()
{
try
{
// Use pages of 10.
var request = new ListThingsRequest()
{
MaxResults = 10
};
var response = await _amazonIoT.ListThingsAsync(request);
// Since there is not a built-in paginator, use the NextMarker to paginate.
bool hasMoreResults = true;
var things = new List();
while (hasMoreResults)
{
things.AddRange(response.Things);
// If NextMarker is not null, there are more results. Get the next page of results.
if (!String.IsNullOrEmpty(response.NextMarker))
{
request.Marker = response.NextMarker;
response = await _amazonIoT.ListThingsAsync(request);
}
else
hasMoreResults = false;
}
_logger.LogInformation($"Retrieved {things.Count} Things");
return things;
}
catch (Amazon.IoT.Model.ThrottlingException ex)
{
_logger.LogWarning($"Request throttled, please try again later: {ex.Message}");
return new List();
}
catch (Exception ex)
{
_logger.LogError($"Couldn't list Things. Here's why: {ex.Message}");
return new List();
}
}
```
+ For API details, see [ListThings](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/ListThings) in *AWS SDK for .NET API Reference*.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list all things in the registry**
The following `list-things` example lists the things (devices) that are defined in the AWS IoT registry for your AWS account.
```
aws iot list-things
```
Output:
```
{
"things": [
{
"thingName": "ThirdBulb",
"thingTypeName": "LightBulb",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/ThirdBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 2
},
{
"thingName": "MyOtherLightBulb",
"thingTypeName": "LightBulb",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyOtherLightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 3
},
{
"thingName": "MyLightBulb",
"thingTypeName": "LightBulb",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyLightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1
},
{
"thingName": "SampleIoTThing",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/SampleIoTThing",
"attributes": {},
"version": 1
}
]
}
```
**Example 2: To list the defined things that have a specific attribute**
The following `list-things` example displays a list of things that have an attribute named `wattage`.
```
aws iot list-things \
--attribute-name wattage
```
Output:
```
{
"things": [
{
"thingName": "MyLightBulb",
"thingTypeName": "LightBulb",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyLightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1
},
{
"thingName": "MyOtherLightBulb",
"thingTypeName": "LightBulb",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyOtherLightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 3
}
]
}
```
For more information, see [How to Manage Things with the Registry](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html) in the *AWS IoT Developers Guide*.
+ For API details, see [ListThings](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-things.html) in *AWS CLI Command Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def list_things(self):
"""
Lists AWS IoT things.
:return: The list of things.
"""
try:
things = []
paginator = self.iot_client.get_paginator("list_things")
for page in paginator.paginate():
things.extend(page["things"])
logger.info("Retrieved %s things.", len(things))
return things
except ClientError as err:
if err.response["Error"]["Code"] == "ThrottlingException":
logger.error("Request throttled. Please try again later.")
else:
logger.error(
"Couldn't list things. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [ListThings](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/ListThings) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/iot#code-examples).
```
async fn show_things(client: &Client) -> Result<(), Error> {
let resp = client.list_things().send().await?;
println!("Things:");
for thing in resp.things.unwrap() {
println!(
" Name: {}",
thing.thing_name.as_deref().unwrap_or_default()
);
println!(
" Type: {}",
thing.thing_type_name.as_deref().unwrap_or_default()
);
println!(
" ARN: {}",
thing.thing_arn.as_deref().unwrap_or_default()
);
println!();
}
println!();
Ok(())
}
```
+ For API details, see [ListThings](https://docs.rs/aws-sdk-iot/latest/aws_sdk_iot/client/struct.Client.html#method.list_things) in *AWS SDK for Rust API reference*.
------
# Use `SearchIndex` with an AWS SDK or CLI
The following code examples show how to use `SearchIndex`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Searches for IoT Things using the search index.
///
/// The search query string.
/// List of Things that match the search criteria, or empty list if search failed.
public async Task> SearchIndexAsync(string queryString)
{
try
{
// First, try to perform the search
var request = new SearchIndexRequest
{
QueryString = queryString
};
var response = await _amazonIoT.SearchIndexAsync(request);
_logger.LogInformation($"Search found {response.Things.Count} Things");
return response.Things;
}
catch (Amazon.IoT.Model.IndexNotReadyException ex)
{
_logger.LogWarning($"Search index not ready, setting up indexing configuration: {ex.Message}");
return await SetupIndexAndRetrySearchAsync(queryString);
}
catch (Amazon.IoT.Model.ResourceNotFoundException ex) when (ex.Message.Contains("index") || ex.Message.Contains("Index"))
{
_logger.LogWarning($"Search index not configured, setting up indexing configuration: {ex.Message}");
return await SetupIndexAndRetrySearchAsync(queryString);
}
catch (Amazon.IoT.Model.ThrottlingException ex)
{
_logger.LogWarning($"Request throttled, please try again later: {ex.Message}");
return new List();
}
catch (Exception ex)
{
_logger.LogError($"Couldn't search index. Here's why: {ex.Message}");
return new List();
}
}
///
/// Sets up the indexing configuration and retries the search after waiting for the index to be ready.
///
/// The search query string.
/// List of Things that match the search criteria, or empty list if setup/search failed.
private async Task> SetupIndexAndRetrySearchAsync(string queryString)
{
try
{
// Update indexing configuration to REGISTRY mode
_logger.LogInformation("Setting up IoT search indexing configuration...");
await _amazonIoT.UpdateIndexingConfigurationAsync(
new UpdateIndexingConfigurationRequest()
{
ThingIndexingConfiguration = new ThingIndexingConfiguration()
{
ThingIndexingMode = ThingIndexingMode.REGISTRY
}
});
_logger.LogInformation("Indexing configuration updated. Waiting for index to be ready...");
// Wait for the index to be set up - this can take some time
const int maxRetries = 10;
const int retryDelaySeconds = 10;
for (int attempt = 1; attempt <= maxRetries; attempt++)
{
try
{
_logger.LogInformation($"Waiting for index to be ready (attempt {attempt}/{maxRetries})...");
await Task.Delay(TimeSpan.FromSeconds(retryDelaySeconds));
// Try to get the current indexing configuration to see if it's ready
var configResponse = await _amazonIoT.GetIndexingConfigurationAsync(new GetIndexingConfigurationRequest());
if (configResponse.ThingIndexingConfiguration?.ThingIndexingMode == ThingIndexingMode.REGISTRY)
{
// Try the search again
var request = new SearchIndexRequest
{
QueryString = queryString
};
var response = await _amazonIoT.SearchIndexAsync(request);
_logger.LogInformation($"Search found {response.Things.Count} Things after index setup");
return response.Things;
}
}
catch (Amazon.IoT.Model.IndexNotReadyException)
{
// Index still not ready, continue waiting
_logger.LogInformation("Index still not ready, continuing to wait...");
continue;
}
catch (Amazon.IoT.Model.InvalidRequestException ex) when (ex.Message.Contains("index") || ex.Message.Contains("Index"))
{
// Index still not ready, continue waiting
_logger.LogInformation("Index still not ready, continuing to wait...");
continue;
}
}
_logger.LogWarning("Timeout waiting for search index to be ready after configuration update");
return new List();
}
catch (Exception ex)
{
_logger.LogError($"Couldn't set up search index configuration. Here's why: {ex.Message}");
return new List();
}
}
```
+ For API details, see [SearchIndex](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/SearchIndex) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Query the AWS IoT fleet index.
//! For query information, see https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html
/*!
\param: query: The query string.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::searchIndex(const Aws::String &query,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::SearchIndexRequest request;
request.SetQueryString(query);
Aws::Vector allThingDocuments;
Aws::String nextToken; // Used for pagination.
do {
if (!nextToken.empty()) {
request.SetNextToken(nextToken);
}
Aws::IoT::Model::SearchIndexOutcome outcome = iotClient.SearchIndex(request);
if (outcome.IsSuccess()) {
const Aws::IoT::Model::SearchIndexResult &result = outcome.GetResult();
allThingDocuments.insert(allThingDocuments.end(),
result.GetThings().cbegin(),
result.GetThings().cend());
nextToken = result.GetNextToken();
}
else {
std::cerr << "Error in SearchIndex: " << outcome.GetError().GetMessage()
<< std::endl;
return false;
}
} while (!nextToken.empty());
std::cout << allThingDocuments.size() << " thing document(s) found." << std::endl;
for (const auto thingDocument: allThingDocuments) {
std::cout << " Thing name: " << thingDocument.GetThingName() << "."
<< std::endl;
}
return true;
}
```
+ For API details, see [SearchIndex](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/SearchIndex) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To query the thing index**
The following `search-index` example queries the `AWS_Things` index for things that have a type of `LightBulb`.
```
aws iot search-index \
--index-name "AWS_Things" \
--query-string "thingTypeName:LightBulb"
```
Output:
```
{
"things": [
{
"thingName": "MyLightBulb",
"thingId": "40da2e73-c6af-406e-b415-15acae538797",
"thingTypeName": "LightBulb",
"thingGroupNames": [
"LightBulbs",
"DeadBulbs"
],
"attributes": {
"model": "123",
"wattage": "75"
},
"connectivity": {
"connected": false
}
},
{
"thingName": "ThirdBulb",
"thingId": "615c8455-33d5-40e8-95fd-3ee8b24490af",
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"connectivity": {
"connected": false
}
},
{
"thingName": "MyOtherLightBulb",
"thingId": "6dae0d3f-40c1-476a-80c4-1ed24ba6aa11",
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"connectivity": {
"connected": false
}
}
]
}
```
For more information, see [Managing Thing Indexing](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) in the *AWS IoT Developer Guide*.
+ For API details, see [SearchIndex](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/search-index.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples).
```
/**
* Searches for IoT Things asynchronously based on a query string.
*
* @param queryString The query string to search for Things.
*
* This method initiates an asynchronous request to search for IoT Things.
* If the request is successful and Things are found, it prints their IDs.
* If no Things are found, it prints a message indicating so.
* If an exception occurs, it prints the error message.
*/
public void searchThings(String queryString) {
SearchIndexRequest searchIndexRequest = SearchIndexRequest.builder()
.queryString(queryString)
.build();
CompletableFuture future = getAsyncClient().searchIndex(searchIndexRequest);
future.whenComplete((searchIndexResponse, ex) -> {
if (searchIndexResponse != null) {
// Process the result.
if (searchIndexResponse.things().isEmpty()) {
System.out.println("No things found.");
} else {
searchIndexResponse.things().forEach(thing -> System.out.println("Thing id found using search is " + thing.thingId()));
}
} else {
Throwable cause = ex != null ? ex.getCause() : null;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else if (cause != null) {
System.err.println("Unexpected error: " + cause.getMessage());
} else {
System.err.println("Failed to search for IoT Things.");
}
}
});
future.join();
}
```
+ For API details, see [SearchIndex](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-2015-05-28/SearchIndex) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun searchThings(queryStringVal: String?) {
val searchIndexRequest =
SearchIndexRequest {
queryString = queryStringVal
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
val searchIndexResponse = iotClient.searchIndex(searchIndexRequest)
if (searchIndexResponse.things?.isEmpty() == true) {
println("No things found.")
} else {
searchIndexResponse.things
?.forEach { thing -> println("Thing id found using search is ${thing.thingId}") }
}
}
}
```
+ For API details, see [SearchIndex](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def search_index(self, query):
"""
Searches the AWS IoT index.
:param query: The search query.
:return: The list of things found.
"""
try:
response = self.iot_client.search_index(queryString=query)
logger.info("Found %s things.", len(response.get("things", [])))
except ClientError as err:
if err.response["Error"]["Code"] == "ThrottlingException":
logger.error("Request throttled. Please try again later.")
else:
logger.error(
"Couldn't search index. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response.get("things", [])
```
+ For API details, see [SearchIndex](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/SearchIndex) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `UpdateIndexingConfiguration` with an AWS SDK or CLI
The following code examples show how to use `UpdateIndexingConfiguration`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Update the indexing configuration.
/*!
\param thingIndexingConfiguration: A ThingIndexingConfiguration object which is ignored if not set.
\param thingGroupIndexingConfiguration: A ThingGroupIndexingConfiguration object which is ignored if not set.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::updateIndexingConfiguration(
const Aws::IoT::Model::ThingIndexingConfiguration &thingIndexingConfiguration,
const Aws::IoT::Model::ThingGroupIndexingConfiguration &thingGroupIndexingConfiguration,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::UpdateIndexingConfigurationRequest request;
if (thingIndexingConfiguration.ThingIndexingModeHasBeenSet()) {
request.SetThingIndexingConfiguration(thingIndexingConfiguration);
}
if (thingGroupIndexingConfiguration.ThingGroupIndexingModeHasBeenSet()) {
request.SetThingGroupIndexingConfiguration(thingGroupIndexingConfiguration);
}
Aws::IoT::Model::UpdateIndexingConfigurationOutcome outcome = iotClient.UpdateIndexingConfiguration(
request);
if (outcome.IsSuccess()) {
std::cout << "UpdateIndexingConfiguration succeeded." << std::endl;
}
else {
std::cerr << "UpdateIndexingConfiguration failed."
<< outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [UpdateIndexingConfiguration](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/UpdateIndexingConfiguration) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To enable thing indexing**
The following `update-indexing-configuration` example enables thing indexing to support searching registry data, shadow data, and thing connectivity status using the AWS\$1Things index.
```
aws iot update-indexing-configuration
--thing-indexing-configuration thingIndexingMode=REGISTRY_AND_SHADOW,thingConnectivityIndexingMode=STATUS
```
This command produces no output.
For more information, see [Managing Thing Indexing](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) in the *AWS IoT Developers Guide*.
+ For API details, see [UpdateIndexingConfiguration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-indexing-configuration.html) in *AWS CLI Command Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples).
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def update_indexing_configuration(self):
"""
Updates the AWS IoT indexing configuration to enable thing indexing.
"""
try:
self.iot_client.update_indexing_configuration(
thingIndexingConfiguration={"thingIndexingMode": "REGISTRY"}
)
logger.info("Updated indexing configuration.")
except ClientError as err:
logger.error(
"Couldn't update indexing configuration. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [UpdateIndexingConfiguration](https://docs.aws.amazon.com/goto/boto3/iot-2015-05-28/UpdateIndexingConfiguration) in *AWS SDK for Python (Boto3) API Reference*.
------
# Use `UpdateThing` with an AWS SDK or CLI
The following code examples show how to use `UpdateThing`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](iot_example_iot_Scenario_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples).
```
///
/// Updates an IoT Thing with attributes.
///
/// The name of the Thing to update.
/// Dictionary of attributes to add.
/// True if successful, false otherwise.
public async Task UpdateThingAsync(string thingName, Dictionary attributes)
{
try
{
var request = new UpdateThingRequest
{
ThingName = thingName,
AttributePayload = new AttributePayload
{
Attributes = attributes,
Merge = true
}
};
await _amazonIoT.UpdateThingAsync(request);
_logger.LogInformation($"Updated Thing {thingName} with attributes");
return true;
}
catch (Amazon.IoT.Model.ResourceNotFoundException ex)
{
_logger.LogError($"Cannot update Thing - resource not found: {ex.Message}");
return false;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't update Thing attributes. Here's why: {ex.Message}");
return false;
}
}
```
+ For API details, see [UpdateThing](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-2015-05-28/UpdateThing) in *AWS SDK for .NET API Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples).
```
//! Update an AWS IoT thing with attributes.
/*!
\param thingName: The name for the thing.
\param attributeMap: A map of key/value attributes/
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::updateThing(const Aws::String &thingName,
const std::map &attributeMap,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoT::IoTClient iotClient(clientConfiguration);
Aws::IoT::Model::UpdateThingRequest request;
request.SetThingName(thingName);
Aws::IoT::Model::AttributePayload attributePayload;
for (const auto &attribute: attributeMap) {
attributePayload.AddAttributes(attribute.first, attribute.second);
}
request.SetAttributePayload(attributePayload);
Aws::IoT::Model::UpdateThingOutcome outcome = iotClient.UpdateThing(request);
if (outcome.IsSuccess()) {
std::cout << "Successfully updated thing " << thingName << std::endl;
}
else {
std::cerr << "Failed to update thing " << thingName << ":" <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ For API details, see [UpdateThing](https://docs.aws.amazon.com/goto/SdkForCpp/iot-2015-05-28/UpdateThing) in *AWS SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To associate a thing with a thing type**
The following `update-thing` example associates a thing in the AWS IoT registry with a thing type. When you make the association, you provide values for the attributes defined by the thing type.
```
aws iot update-thing \
--thing-name "MyOtherLightBulb" \
--thing-type-name "LightBulb" \
--attribute-payload "{"attributes": {"wattage":"75", "model":"123"}}"
```
This command does not produce output. Use the `describe-thing` command to see the result.
For more information, see [Thing Types](https://docs.aws.amazon.com/iot/latest/developerguide/thing-types.html) in the *AWS IoT Developers Guide*.
+ For API details, see [UpdateThing](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-thing.html) in *AWS CLI Command Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples).
```
suspend fun updateThing(thingNameVal: String?) {
val newLocation = "Office"
val newFirmwareVersion = "v2.0"
val attMap: MutableMap = HashMap()
attMap["location"] = newLocation
attMap["firmwareVersion"] = newFirmwareVersion
val attributePayloadVal =
AttributePayload {
attributes = attMap
}
val updateThingRequest =
UpdateThingRequest {
thingName = thingNameVal
attributePayload = attributePayloadVal
}
IotClient.fromEnvironment { region = "us-east-1" }.use { iotClient ->
// Update the IoT thing attributes.
iotClient.updateThing(updateThingRequest)
println("$thingNameVal attributes updated successfully.")
}
}
```
+ For API details, see [UpdateThing](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------