* Note: Do not directly implement this interface, new methods are added to it regularly. Extend from * {@link com.amazonaws.services.iotdata.AbstractAWSIotData} instead. *
*
*
* IoT data enables secure, bi-directional communication between Internet-connected things (such as sensors, actuators, * embedded devices, or smart appliances) and the Amazon Web Services cloud. It implements a broker for applications and * things to publish messages over HTTP (Publish) and retrieve, update, and delete shadows. A shadow is a persistent * representation of your things and their state in the Amazon Web Services cloud. *
** Find the endpoint address for actions in IoT data by running this CLI command: *
*
* aws iot describe-endpoint --endpoint-type iot:Data-ATS
*
* The service name used by Amazon Web * ServicesSignature Version 4 to sign requests is: iotdevicegateway. *
*/ @Generated("com.amazonaws:aws-java-sdk-code-generator") public interface AWSIotData { /** * The region metadata service name for computing region endpoints. You can use this value to retrieve metadata * (such as supported regions) of the service. * * @see RegionUtils#getRegionsForService(String) */ String ENDPOINT_PREFIX = "data-ats.iot"; /** * Overrides the default endpoint for this client ("https://data.iot.us-east-1.amazonaws.com"). Callers can use this * method to control which AWS region they want to work with. ** Callers can pass in just the endpoint (ex: "data.iot.us-east-1.amazonaws.com") or a full URL, including the * protocol (ex: "https://data.iot.us-east-1.amazonaws.com"). If the protocol is not specified here, the default * protocol from this client's {@link ClientConfiguration} will be used, which by default is HTTPS. *
* For more information on using AWS regions with the AWS SDK for Java, and a complete list of all available * endpoints for all AWS services, see: https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-region-selection.html#region-selection- * choose-endpoint *
* This method is not threadsafe. An endpoint should be configured when the client is created and before any * service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in * transit or retrying. * * @param endpoint * The endpoint (ex: "data.iot.us-east-1.amazonaws.com") or a full URL, including the protocol (ex: * "https://data.iot.us-east-1.amazonaws.com") of the region specific AWS endpoint this client will * communicate with. * @deprecated use {@link AwsClientBuilder#setEndpointConfiguration(AwsClientBuilder.EndpointConfiguration)} for * example: * {@code builder.setEndpointConfiguration(new EndpointConfiguration(endpoint, signingRegion));} */ @Deprecated void setEndpoint(String endpoint); /** * An alternative to {@link AWSIotData#setEndpoint(String)}, sets the regional endpoint for this client's service * calls. Callers can use this method to control which AWS region they want to work with. *
* By default, all service endpoints in all regions use the https protocol. To use http instead, specify it in the * {@link ClientConfiguration} supplied at construction. *
* This method is not threadsafe. A region should be configured when the client is created and before any service * requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit * or retrying. * * @param region * The region this client will communicate with. See {@link Region#getRegion(com.amazonaws.regions.Regions)} * for accessing a given region. Must not be null and must be a region where the service is available. * * @see Region#getRegion(com.amazonaws.regions.Regions) * @see Region#createClient(Class, com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration) * @see Region#isServiceSupported(String) * @deprecated use {@link AwsClientBuilder#setRegion(String)} */ @Deprecated void setRegion(Region region); /** *
* Deletes the shadow for the specified thing. *
** Requires permission to access the DeleteThingShadow action. *
** For more information, see DeleteThingShadow in * the IoT Developer Guide. *
* * @param deleteThingShadowRequest * The input for the DeleteThingShadow operation. * @return Result of the DeleteThingShadow operation returned by the service. * @throws ResourceNotFoundException * The specified resource does not exist. * @throws InvalidRequestException * The request is not valid. * @throws ThrottlingException * The rate exceeds the limit. * @throws UnauthorizedException * You are not authorized to perform this operation. * @throws ServiceUnavailableException * The service is temporarily unavailable. * @throws InternalFailureException * An unexpected error has occurred. * @throws MethodNotAllowedException * The specified combination of HTTP verb and URI is not supported. * @throws UnsupportedDocumentEncodingException * The document encoding is not supported. * @sample AWSIotData.DeleteThingShadow * @see AWS API * Documentation */ DeleteThingShadowResult deleteThingShadow(DeleteThingShadowRequest deleteThingShadowRequest); /** ** Gets the details of a single retained message for the specified topic. *
** This action returns the message payload of the retained message, which can incur messaging costs. To list only * the topic names of the retained messages, call ListRetainedMessages. *
** Requires permission to access the GetRetainedMessage action. *
** For more information about messaging costs, see Amazon Web Services IoT Core pricing - Messaging. *
* * @param getRetainedMessageRequest * The input for the GetRetainedMessage operation. * @return Result of the GetRetainedMessage operation returned by the service. * @throws InvalidRequestException * The request is not valid. * @throws ResourceNotFoundException * The specified resource does not exist. * @throws ThrottlingException * The rate exceeds the limit. * @throws UnauthorizedException * You are not authorized to perform this operation. * @throws ServiceUnavailableException * The service is temporarily unavailable. * @throws InternalFailureException * An unexpected error has occurred. * @throws MethodNotAllowedException * The specified combination of HTTP verb and URI is not supported. * @sample AWSIotData.GetRetainedMessage * @see AWS * API Documentation */ GetRetainedMessageResult getRetainedMessage(GetRetainedMessageRequest getRetainedMessageRequest); /** ** Gets the shadow for the specified thing. *
** Requires permission to access the GetThingShadow action. *
** For more information, see GetThingShadow in the IoT * Developer Guide. *
* * @param getThingShadowRequest * The input for the GetThingShadow operation. * @return Result of the GetThingShadow operation returned by the service. * @throws InvalidRequestException * The request is not valid. * @throws ResourceNotFoundException * The specified resource does not exist. * @throws ThrottlingException * The rate exceeds the limit. * @throws UnauthorizedException * You are not authorized to perform this operation. * @throws ServiceUnavailableException * The service is temporarily unavailable. * @throws InternalFailureException * An unexpected error has occurred. * @throws MethodNotAllowedException * The specified combination of HTTP verb and URI is not supported. * @throws UnsupportedDocumentEncodingException * The document encoding is not supported. * @sample AWSIotData.GetThingShadow * @see AWS API * Documentation */ GetThingShadowResult getThingShadow(GetThingShadowRequest getThingShadowRequest); /** ** Lists the shadows for the specified thing. *
** Requires permission to access the ListNamedShadowsForThing action. *
* * @param listNamedShadowsForThingRequest * @return Result of the ListNamedShadowsForThing operation returned by the service. * @throws ResourceNotFoundException * The specified resource does not exist. * @throws InvalidRequestException * The request is not valid. * @throws ThrottlingException * The rate exceeds the limit. * @throws UnauthorizedException * You are not authorized to perform this operation. * @throws ServiceUnavailableException * The service is temporarily unavailable. * @throws InternalFailureException * An unexpected error has occurred. * @throws MethodNotAllowedException * The specified combination of HTTP verb and URI is not supported. * @sample AWSIotData.ListNamedShadowsForThing * @see AWS API Documentation */ ListNamedShadowsForThingResult listNamedShadowsForThing(ListNamedShadowsForThingRequest listNamedShadowsForThingRequest); /** ** Lists summary information about the retained messages stored for the account. *
** This action returns only the topic names of the retained messages. It doesn't return any message payloads. * Although this action doesn't return a message payload, it can still incur messaging costs. *
** To get the message payload of a retained message, call GetRetainedMessage with the topic name of the retained message. *
** Requires permission to access the ListRetainedMessages action. *
** For more information about messaging costs, see Amazon Web Services IoT Core pricing - Messaging. *
* * @param listRetainedMessagesRequest * @return Result of the ListRetainedMessages operation returned by the service. * @throws InvalidRequestException * The request is not valid. * @throws ThrottlingException * The rate exceeds the limit. * @throws UnauthorizedException * You are not authorized to perform this operation. * @throws ServiceUnavailableException * The service is temporarily unavailable. * @throws InternalFailureException * An unexpected error has occurred. * @throws MethodNotAllowedException * The specified combination of HTTP verb and URI is not supported. * @sample AWSIotData.ListRetainedMessages * @see AWS * API Documentation */ ListRetainedMessagesResult listRetainedMessages(ListRetainedMessagesRequest listRetainedMessagesRequest); /** ** Publishes an MQTT message. *
** Requires permission to access the Publish action. *
** For more information about MQTT messages, see MQTT Protocol in the IoT Developer * Guide. *
** For more information about messaging costs, see Amazon Web Services IoT Core pricing - Messaging. *
* * @param publishRequest * The input for the Publish operation. * @return Result of the Publish operation returned by the service. * @throws InternalFailureException * An unexpected error has occurred. * @throws InvalidRequestException * The request is not valid. * @throws UnauthorizedException * You are not authorized to perform this operation. * @throws MethodNotAllowedException * The specified combination of HTTP verb and URI is not supported. * @throws ThrottlingException * The rate exceeds the limit. * @sample AWSIotData.Publish * @see AWS API * Documentation */ PublishResult publish(PublishRequest publishRequest); /** ** Updates the shadow for the specified thing. *
** Requires permission to access the UpdateThingShadow action. *
** For more information, see UpdateThingShadow in * the IoT Developer Guide. *
* * @param updateThingShadowRequest * The input for the UpdateThingShadow operation. * @return Result of the UpdateThingShadow operation returned by the service. * @throws ConflictException * The specified version does not match the version of the document. * @throws RequestEntityTooLargeException * The payload exceeds the maximum size allowed. * @throws InvalidRequestException * The request is not valid. * @throws ThrottlingException * The rate exceeds the limit. * @throws UnauthorizedException * You are not authorized to perform this operation. * @throws ServiceUnavailableException * The service is temporarily unavailable. * @throws InternalFailureException * An unexpected error has occurred. * @throws MethodNotAllowedException * The specified combination of HTTP verb and URI is not supported. * @throws UnsupportedDocumentEncodingException * The document encoding is not supported. * @sample AWSIotData.UpdateThingShadow * @see AWS API * Documentation */ UpdateThingShadowResult updateThingShadow(UpdateThingShadowRequest updateThingShadowRequest); /** * Shuts down this client object, releasing any resources that might be held open. This is an optional method, and * callers are not expected to call it, but can if they want to explicitly release any open resources. Once a client * has been shutdown, it should not be used to make any more requests. */ void shutdown(); /** * Returns additional metadata for a previously executed successful request, typically used for debugging issues * where a service isn't acting as expected. This data isn't considered part of the result data returned by an * operation, so it's available through this separate, diagnostic interface. ** Response metadata is only cached for a limited period of time, so if you need to access this extra diagnostic * information for an executed request, you should use this method to retrieve it as soon as possible after * executing a request. * * @param request * The originally executed request. * * @return The response metadata for the specified request, or null if none is available. */ ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request); }