AWS IoT Secure Tunneling 2018-10-05
- Client: Aws\IoTSecureTunneling\IoTSecureTunnelingClient
- Service ID: iotsecuretunneling
- Version: 2018-10-05
This page describes the parameters and results for the operations of the AWS IoT Secure Tunneling (2018-10-05), and shows how to use the Aws\IoTSecureTunneling\IoTSecureTunnelingClient object to call the described operations. This documentation is specific to the 2018-10-05 API version of the service.
Operation Summary
Each of the following operations can be created from a client using
$client->getCommand('CommandName'), where "CommandName" is the
name of one of the following operations. Note: a command is a value that
encapsulates an operation and the parameters used to create an HTTP request.
You can also create and send a command immediately using the magic methods
available on a client object: $client->commandName(/* parameters */).
You can send the command asynchronously (returning a promise) by appending the
word "Async" to the operation name: $client->commandNameAsync(/* parameters */).
- CloseTunnel ( array $params = [] )
Closes a tunnel identified by the unique tunnel id.
- DescribeTunnel ( array $params = [] )
Gets information about a tunnel identified by the unique tunnel id.
- ListTagsForResource ( array $params = [] )
Lists the tags for the specified resource.
- ListTunnels ( array $params = [] )
List all tunnels for an Amazon Web Services account.
- OpenTunnel ( array $params = [] )
Creates a new tunnel, and returns two client access tokens for clients to use to connect to the IoT Secure Tunneling proxy server.
- RotateTunnelAccessToken ( array $params = [] )
Revokes the current client access token (CAT) and returns new CAT for clients to use when reconnecting to secure tunneling to access the same tunnel.
- TagResource ( array $params = [] )
A resource tag.
- UntagResource ( array $params = [] )
Removes a tag from a resource.
Paginators
Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:
Operations
CloseTunnel
$result = $client->closeTunnel([/* ... */]); $promise = $client->closeTunnelAsync([/* ... */]);
Closes a tunnel identified by the unique tunnel id. When a CloseTunnel request is received, we close the WebSocket connections between the client and proxy server so no data can be transmitted.
Requires permission to access the CloseTunnel action.
Parameter Syntax
$result = $client->closeTunnel([
'delete' => true || false,
'tunnelId' => '<string>', // REQUIRED
]);
Parameter Details
Members
Result Syntax
[]
Result Details
Errors
-
Thrown when an operation is attempted on a resource that does not exist.
DescribeTunnel
$result = $client->describeTunnel([/* ... */]); $promise = $client->describeTunnelAsync([/* ... */]);
Gets information about a tunnel identified by the unique tunnel id.
Requires permission to access the DescribeTunnel action.
Parameter Syntax
$result = $client->describeTunnel([
'tunnelId' => '<string>', // REQUIRED
]);
Parameter Details
Result Syntax
[
'tunnel' => [
'createdAt' => <DateTime>,
'description' => '<string>',
'destinationConfig' => [
'services' => ['<string>', ...],
'thingName' => '<string>',
],
'destinationConnectionState' => [
'lastUpdatedAt' => <DateTime>,
'status' => 'CONNECTED|DISCONNECTED',
],
'lastUpdatedAt' => <DateTime>,
'sourceConnectionState' => [
'lastUpdatedAt' => <DateTime>,
'status' => 'CONNECTED|DISCONNECTED',
],
'status' => 'OPEN|CLOSED',
'tags' => [
[
'key' => '<string>',
'value' => '<string>',
],
// ...
],
'timeoutConfig' => [
'maxLifetimeTimeoutMinutes' => <integer>,
],
'tunnelArn' => '<string>',
'tunnelId' => '<string>',
],
]
Result Details
Members
- tunnel
-
- Type: Tunnel structure
The tunnel being described.
Errors
-
Thrown when an operation is attempted on a resource that does not exist.
ListTagsForResource
$result = $client->listTagsForResource([/* ... */]); $promise = $client->listTagsForResourceAsync([/* ... */]);
Lists the tags for the specified resource.
Parameter Syntax
$result = $client->listTagsForResource([
'resourceArn' => '<string>', // REQUIRED
]);
Parameter Details
Result Syntax
[
'tags' => [
[
'key' => '<string>',
'value' => '<string>',
],
// ...
],
]
Result Details
Members
- tags
-
- Type: Array of Tag structures
The tags for the specified resource.
Errors
-
Thrown when an operation is attempted on a resource that does not exist.
ListTunnels
$result = $client->listTunnels([/* ... */]); $promise = $client->listTunnelsAsync([/* ... */]);
List all tunnels for an Amazon Web Services account. Tunnels are listed by creation time in descending order, newer tunnels will be listed before older tunnels.
Requires permission to access the ListTunnels action.
Parameter Syntax
$result = $client->listTunnels([
'maxResults' => <integer>,
'nextToken' => '<string>',
'thingName' => '<string>',
]);
Parameter Details
Members
- maxResults
-
- Type: int
The maximum number of results to return at once.
- nextToken
-
- Type: string
To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.
- thingName
-
- Type: string
The name of the IoT thing associated with the destination device.
Result Syntax
[
'nextToken' => '<string>',
'tunnelSummaries' => [
[
'createdAt' => <DateTime>,
'description' => '<string>',
'lastUpdatedAt' => <DateTime>,
'status' => 'OPEN|CLOSED',
'tunnelArn' => '<string>',
'tunnelId' => '<string>',
],
// ...
],
]
Result Details
Members
- nextToken
-
- Type: string
The token to use to get the next set of results, or null if there are no additional results.
- tunnelSummaries
-
- Type: Array of TunnelSummary structures
A short description of the tunnels in an Amazon Web Services account.
Errors
There are no errors described for this operation.
OpenTunnel
$result = $client->openTunnel([/* ... */]); $promise = $client->openTunnelAsync([/* ... */]);
Creates a new tunnel, and returns two client access tokens for clients to use to connect to the IoT Secure Tunneling proxy server.
Requires permission to access the OpenTunnel action.
Parameter Syntax
$result = $client->openTunnel([
'description' => '<string>',
'destinationConfig' => [
'services' => ['<string>', ...], // REQUIRED
'thingName' => '<string>',
],
'tags' => [
[
'key' => '<string>', // REQUIRED
'value' => '<string>', // REQUIRED
],
// ...
],
'timeoutConfig' => [
'maxLifetimeTimeoutMinutes' => <integer>,
],
]);
Parameter Details
Members
- description
-
- Type: string
A short text description of the tunnel.
- destinationConfig
-
- Type: DestinationConfig structure
The destination configuration for the OpenTunnel request.
- tags
-
- Type: Array of Tag structures
A collection of tag metadata.
- timeoutConfig
-
- Type: TimeoutConfig structure
Timeout configuration for a tunnel.
Result Syntax
[
'destinationAccessToken' => '<string>',
'sourceAccessToken' => '<string>',
'tunnelArn' => '<string>',
'tunnelId' => '<string>',
]
Result Details
Members
- destinationAccessToken
-
- Type: string
The access token the destination local proxy uses to connect to IoT Secure Tunneling.
- sourceAccessToken
-
- Type: string
The access token the source local proxy uses to connect to IoT Secure Tunneling.
- tunnelArn
-
- Type: string
The Amazon Resource Name for the tunnel.
- tunnelId
-
- Type: string
A unique alpha-numeric tunnel ID.
Errors
-
Thrown when a tunnel limit is exceeded.
RotateTunnelAccessToken
$result = $client->rotateTunnelAccessToken([/* ... */]); $promise = $client->rotateTunnelAccessTokenAsync([/* ... */]);
Revokes the current client access token (CAT) and returns new CAT for clients to use when reconnecting to secure tunneling to access the same tunnel.
Requires permission to access the RotateTunnelAccessToken action.
Rotating the CAT doesn't extend the tunnel duration. For example, say the tunnel duration is 12 hours and the tunnel has already been open for 4 hours. When you rotate the access tokens, the new tokens that are generated can only be used for the remaining 8 hours.
Parameter Syntax
$result = $client->rotateTunnelAccessToken([
'clientMode' => 'SOURCE|DESTINATION|ALL', // REQUIRED
'destinationConfig' => [
'services' => ['<string>', ...], // REQUIRED
'thingName' => '<string>',
],
'tunnelId' => '<string>', // REQUIRED
]);
Parameter Details
Members
- clientMode
-
- Required: Yes
- Type: string
The mode of the client that will use the client token, which can be either the source or destination, or both source and destination.
- destinationConfig
-
- Type: DestinationConfig structure
The destination configuration.
- tunnelId
-
- Required: Yes
- Type: string
The tunnel for which you want to rotate the access tokens.
Result Syntax
[
'destinationAccessToken' => '<string>',
'sourceAccessToken' => '<string>',
'tunnelArn' => '<string>',
]
Result Details
Members
- destinationAccessToken
-
- Type: string
The client access token that the destination local proxy uses to connect to IoT Secure Tunneling.
- sourceAccessToken
-
- Type: string
The client access token that the source local proxy uses to connect to IoT Secure Tunneling.
- tunnelArn
-
- Type: string
The Amazon Resource Name for the tunnel.
Errors
-
Thrown when an operation is attempted on a resource that does not exist.
TagResource
$result = $client->tagResource([/* ... */]); $promise = $client->tagResourceAsync([/* ... */]);
A resource tag.
Parameter Syntax
$result = $client->tagResource([
'resourceArn' => '<string>', // REQUIRED
'tags' => [ // REQUIRED
[
'key' => '<string>', // REQUIRED
'value' => '<string>', // REQUIRED
],
// ...
],
]);
Parameter Details
Members
- resourceArn
-
- Required: Yes
- Type: string
The ARN of the resource.
- tags
-
- Required: Yes
- Type: Array of Tag structures
The tags for the resource.
Result Syntax
[]
Result Details
Errors
-
Thrown when an operation is attempted on a resource that does not exist.
UntagResource
$result = $client->untagResource([/* ... */]); $promise = $client->untagResourceAsync([/* ... */]);
Removes a tag from a resource.
Parameter Syntax
$result = $client->untagResource([
'resourceArn' => '<string>', // REQUIRED
'tagKeys' => ['<string>', ...], // REQUIRED
]);
Parameter Details
Members
Result Syntax
[]
Result Details
Errors
-
Thrown when an operation is attempted on a resource that does not exist.
Shapes
ConnectionState
Description
The state of a connection.
Members
DestinationConfig
Description
The destination configuration.
Members
- services
-
- Required: Yes
- Type: Array of strings
A list of service names that identify the target application. The IoT client running on the destination device reads this value and uses it to look up a port or an IP address and a port. The IoT client instantiates the local proxy, which uses this information to connect to the destination application.
- thingName
-
- Type: string
The name of the IoT thing to which you want to connect.
LimitExceededException
ResourceNotFoundException
Description
Thrown when an operation is attempted on a resource that does not exist.
Members
Tag
Description
An arbitary key/value pair used to add searchable metadata to secure tunnel resources.
Members
TimeoutConfig
Description
Tunnel timeout configuration.
Members
Tunnel
Description
A connection between a source computer and a destination device.
Members
- createdAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The time when the tunnel was created.
- description
-
- Type: string
A description of the tunnel.
- destinationConfig
-
- Type: DestinationConfig structure
The destination configuration that specifies the thing name of the destination device and a service name that the local proxy uses to connect to the destination application.
- destinationConnectionState
-
- Type: ConnectionState structure
The connection state of the destination application.
- lastUpdatedAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The last time the tunnel was updated.
- sourceConnectionState
-
- Type: ConnectionState structure
The connection state of the source application.
- status
-
- Type: string
The status of a tunnel. Valid values are: Open and Closed.
- tags
-
- Type: Array of Tag structures
A list of tag metadata associated with the secure tunnel.
- timeoutConfig
-
- Type: TimeoutConfig structure
Timeout configuration for the tunnel.
- tunnelArn
-
- Type: string
The Amazon Resource Name (ARN) of a tunnel.
- tunnelId
-
- Type: string
A unique alpha-numeric ID that identifies a tunnel.
TunnelSummary
Description
Information about the tunnel.
Members
- createdAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The time the tunnel was created.
- description
-
- Type: string
A description of the tunnel.
- lastUpdatedAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The time the tunnel was last updated.
- status
-
- Type: string
The status of a tunnel. Valid values are: Open and Closed.
- tunnelArn
-
- Type: string
The Amazon Resource Name of the tunnel.
- tunnelId
-
- Type: string
The unique alpha-numeric identifier for the tunnel.