SDK for PHP 3.x

AWS IoT 1-Click Projects Service 2018-05-14

Client: Aws\IoT1ClickProjects\IoT1ClickProjectsClient
Service ID: iot1click-projects
Version: 2018-05-14

This page describes the parameters and results for the operations of the AWS IoT 1-Click Projects Service (2018-05-14), and shows how to use the Aws\IoT1ClickProjects\IoT1ClickProjectsClient object to call the described operations. This documentation is specific to the 2018-05-14 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 */).

AssociateDeviceWithPlacement ( array $params = [] )
Associates a physical device with a placement.
CreatePlacement ( array $params = [] )
Creates an empty placement.
CreateProject ( array $params = [] )
Creates an empty project with a placement template.
DeletePlacement ( array $params = [] )
Deletes a placement.
DeleteProject ( array $params = [] )
Deletes a project.
DescribePlacement ( array $params = [] )
Describes a placement in a project.
DescribeProject ( array $params = [] )
Returns an object describing a project.
DisassociateDeviceFromPlacement ( array $params = [] )
Removes a physical device from a placement.
GetDevicesInPlacement ( array $params = [] )
Returns an object enumerating the devices in a placement.
ListPlacements ( array $params = [] )
Lists the placement(s) of a project.
ListProjects ( array $params = [] )
Lists the AWS IoT 1-Click project(s) associated with your AWS account and region.
ListTagsForResource ( array $params = [] )
Lists the tags (metadata key/value pairs) which you have assigned to the resource.
TagResource ( array $params = [] )
Creates or modifies tags for a resource.
UntagResource ( array $params = [] )
Removes one or more tags (metadata key/value pairs) from a resource.
UpdatePlacement ( array $params = [] )
Updates a placement with the given attributes.
UpdateProject ( array $params = [] )
Updates a project associated with your AWS account and region.

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:

ListPlacements
ListProjects

Operations

AssociateDeviceWithPlacement 

$result = $client->associateDeviceWithPlacement([/* ... */]);
$promise = $client->associateDeviceWithPlacementAsync([/* ... */]);

Associates a physical device with a placement.

Parameter Syntax

$result = $client->associateDeviceWithPlacement([
    'deviceId' => '<string>', // REQUIRED
    'deviceTemplateName' => '<string>', // REQUIRED
    'placementName' => '<string>', // REQUIRED
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
deviceId
Required: Yes
Type: string

The ID of the physical device to be associated with the given placement in the project. Note that a mandatory 4 character prefix is required for all deviceId values.

deviceTemplateName
Required: Yes
Type: string

The device template name to associate with the device ID.

placementName
Required: Yes
Type: string

The name of the placement in which to associate the device.

projectName
Required: Yes
Type: string

The name of the project containing the placement in which to associate the device.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceConflictException:

ResourceNotFoundException:

CreatePlacement 

$result = $client->createPlacement([/* ... */]);
$promise = $client->createPlacementAsync([/* ... */]);

Creates an empty placement.

Parameter Syntax

$result = $client->createPlacement([
    'attributes' => ['<string>', ...],
    'placementName' => '<string>', // REQUIRED
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
attributes
Type: Associative array of custom strings keys (AttributeName) to strings

Optional user-defined key/value pairs providing contextual data (such as location or function) for the placement.

placementName
Required: Yes
Type: string

The name of the placement to be created.

projectName
Required: Yes
Type: string

The name of the project in which to create the placement.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceConflictException:

ResourceNotFoundException:

CreateProject 

$result = $client->createProject([/* ... */]);
$promise = $client->createProjectAsync([/* ... */]);

Creates an empty project with a placement template. A project contains zero or more placements that adhere to the placement template defined in the project.

Parameter Syntax

$result = $client->createProject([
    'description' => '<string>',
    'placementTemplate' => [
        'defaultAttributes' => ['<string>', ...],
        'deviceTemplates' => [
            '<DeviceTemplateName>' => [
                'callbackOverrides' => ['<string>', ...],
                'deviceType' => '<string>',
            ],
            // ...
        ],
    ],
    'projectName' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
]);

Parameter Details

Members
description
Type: string

An optional description for the project.

placementTemplate
Type: PlacementTemplate structure

The schema defining the placement to be created. A placement template defines placement default attributes and device templates. You cannot add or remove device templates after the project has been created. However, you can update callbackOverrides for the device templates using the UpdateProject API.

projectName
Required: Yes
Type: string

The name of the project to create.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Optional tags (metadata key/value pairs) to be associated with the project. For example, { {"key1": "value1", "key2": "value2"} }. For more information, see AWS Tagging Strategies.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceConflictException:

DeletePlacement 

$result = $client->deletePlacement([/* ... */]);
$promise = $client->deletePlacementAsync([/* ... */]);

Deletes a placement. To delete a placement, it must not have any devices associated with it.

When you delete a placement, all associated data becomes irretrievable.

Parameter Syntax

$result = $client->deletePlacement([
    'placementName' => '<string>', // REQUIRED
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
placementName
Required: Yes
Type: string

The name of the empty placement to delete.

projectName
Required: Yes
Type: string

The project containing the empty placement to delete.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

TooManyRequestsException:

DeleteProject 

$result = $client->deleteProject([/* ... */]);
$promise = $client->deleteProjectAsync([/* ... */]);

Deletes a project. To delete a project, it must not have any placements associated with it.

When you delete a project, all associated data becomes irretrievable.

Parameter Syntax

$result = $client->deleteProject([
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
projectName
Required: Yes
Type: string

The name of the empty project to delete.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

TooManyRequestsException:

DescribePlacement 

$result = $client->describePlacement([/* ... */]);
$promise = $client->describePlacementAsync([/* ... */]);

Describes a placement in a project.

Parameter Syntax

$result = $client->describePlacement([
    'placementName' => '<string>', // REQUIRED
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
placementName
Required: Yes
Type: string

The name of the placement within a project.

projectName
Required: Yes
Type: string

The project containing the placement to be described.

Result Syntax

[
    'placement' => [
        'attributes' => ['<string>', ...],
        'createdDate' => <DateTime>,
        'placementName' => '<string>',
        'projectName' => '<string>',
        'updatedDate' => <DateTime>,
    ],
]

Result Details

Members
placement
Required: Yes
Type: PlacementDescription structure

An object describing the placement.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

DescribeProject 

$result = $client->describeProject([/* ... */]);
$promise = $client->describeProjectAsync([/* ... */]);

Returns an object describing a project.

Parameter Syntax

$result = $client->describeProject([
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
projectName
Required: Yes
Type: string

The name of the project to be described.

Result Syntax

[
    'project' => [
        'arn' => '<string>',
        'createdDate' => <DateTime>,
        'description' => '<string>',
        'placementTemplate' => [
            'defaultAttributes' => ['<string>', ...],
            'deviceTemplates' => [
                '<DeviceTemplateName>' => [
                    'callbackOverrides' => ['<string>', ...],
                    'deviceType' => '<string>',
                ],
                // ...
            ],
        ],
        'projectName' => '<string>',
        'tags' => ['<string>', ...],
        'updatedDate' => <DateTime>,
    ],
]

Result Details

Members
project
Required: Yes
Type: ProjectDescription structure

An object describing the project.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

DisassociateDeviceFromPlacement 

$result = $client->disassociateDeviceFromPlacement([/* ... */]);
$promise = $client->disassociateDeviceFromPlacementAsync([/* ... */]);

Removes a physical device from a placement.

Parameter Syntax

$result = $client->disassociateDeviceFromPlacement([
    'deviceTemplateName' => '<string>', // REQUIRED
    'placementName' => '<string>', // REQUIRED
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
deviceTemplateName
Required: Yes
Type: string

The device ID that should be removed from the placement.

placementName
Required: Yes
Type: string

The name of the placement that the device should be removed from.

projectName
Required: Yes
Type: string

The name of the project that contains the placement.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

TooManyRequestsException:

GetDevicesInPlacement 

$result = $client->getDevicesInPlacement([/* ... */]);
$promise = $client->getDevicesInPlacementAsync([/* ... */]);

Returns an object enumerating the devices in a placement.

Parameter Syntax

$result = $client->getDevicesInPlacement([
    'placementName' => '<string>', // REQUIRED
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
placementName
Required: Yes
Type: string

The name of the placement to get the devices from.

projectName
Required: Yes
Type: string

The name of the project containing the placement.

Result Syntax

[
    'devices' => ['<string>', ...],
]

Result Details

Members
devices
Required: Yes
Type: Associative array of custom strings keys (DeviceTemplateName) to strings

An object containing the devices (zero or more) within the placement.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

ListPlacements 

$result = $client->listPlacements([/* ... */]);
$promise = $client->listPlacementsAsync([/* ... */]);

Lists the placement(s) of a project.

Parameter Syntax

$result = $client->listPlacements([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
maxResults
Type: int

The maximum number of results to return per request. If not set, a default value of 100 is used.

nextToken
Type: string

The token to retrieve the next set of results.

projectName
Required: Yes
Type: string

The project containing the placements to be listed.

Result Syntax

[
    'nextToken' => '<string>',
    'placements' => [
        [
            'createdDate' => <DateTime>,
            'placementName' => '<string>',
            'projectName' => '<string>',
            'updatedDate' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

The token used to retrieve the next set of results - will be effectively empty if there are no further results.

placements
Required: Yes
Type: Array of PlacementSummary structures

An object listing the requested placements.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

ListProjects 

$result = $client->listProjects([/* ... */]);
$promise = $client->listProjectsAsync([/* ... */]);

Lists the AWS IoT 1-Click project(s) associated with your AWS account and region.

Parameter Syntax

$result = $client->listProjects([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

The maximum number of results to return per request. If not set, a default value of 100 is used.

nextToken
Type: string

The token to retrieve the next set of results.

Result Syntax

[
    'nextToken' => '<string>',
    'projects' => [
        [
            'arn' => '<string>',
            'createdDate' => <DateTime>,
            'projectName' => '<string>',
            'tags' => ['<string>', ...],
            'updatedDate' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

The token used to retrieve the next set of results - will be effectively empty if there are no further results.

projects
Required: Yes
Type: Array of ProjectSummary structures

An object containing the list of projects.

Errors

InternalFailureException:

InvalidRequestException:

ListTagsForResource 

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Lists the tags (metadata key/value pairs) which you have assigned to the resource.

Parameter Syntax

$result = $client->listTagsForResource([
    'resourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The ARN of the resource whose tags you want to list.

Result Syntax

[
    'tags' => ['<string>', ...],
]

Result Details

Members
tags
Type: Associative array of custom strings keys (TagKey) to strings

The tags (metadata key/value pairs) which you have assigned to the resource.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

TagResource 

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Creates or modifies tags for a resource. Tags are key/value pairs (metadata) that can be used to manage a resource. For more information, see AWS Tagging Strategies.

Parameter Syntax

$result = $client->tagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tags' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The ARN of the resouce for which tag(s) should be added or modified.

tags
Required: Yes
Type: Associative array of custom strings keys (TagKey) to strings

The new or modifying tag(s) for the resource. See AWS IoT 1-Click Service Limits for the maximum number of tags allowed per resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

UntagResource 

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes one or more tags (metadata key/value pairs) from a resource.

Parameter Syntax

$result = $client->untagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The ARN of the resource whose tag you want to remove.

tagKeys
Required: Yes
Type: Array of strings

The keys of those tags which you want to remove.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

UpdatePlacement 

$result = $client->updatePlacement([/* ... */]);
$promise = $client->updatePlacementAsync([/* ... */]);

Updates a placement with the given attributes. To clear an attribute, pass an empty value (i.e., "").

Parameter Syntax

$result = $client->updatePlacement([
    'attributes' => ['<string>', ...],
    'placementName' => '<string>', // REQUIRED
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
attributes
Type: Associative array of custom strings keys (AttributeName) to strings

The user-defined object of attributes used to update the placement. The maximum number of key/value pairs is 50.

placementName
Required: Yes
Type: string

The name of the placement to update.

projectName
Required: Yes
Type: string

The name of the project containing the placement to be updated.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

TooManyRequestsException:

UpdateProject 

$result = $client->updateProject([/* ... */]);
$promise = $client->updateProjectAsync([/* ... */]);

Updates a project associated with your AWS account and region. With the exception of device template names, you can pass just the values that need to be updated because the update request will change only the values that are provided. To clear a value, pass the empty string (i.e., "").

Parameter Syntax

$result = $client->updateProject([
    'description' => '<string>',
    'placementTemplate' => [
        'defaultAttributes' => ['<string>', ...],
        'deviceTemplates' => [
            '<DeviceTemplateName>' => [
                'callbackOverrides' => ['<string>', ...],
                'deviceType' => '<string>',
            ],
            // ...
        ],
    ],
    'projectName' => '<string>', // REQUIRED
]);

Parameter Details

Members
description
Type: string

An optional user-defined description for the project.

placementTemplate
Type: PlacementTemplate structure

An object defining the project update. Once a project has been created, you cannot add device template names to the project. However, for a given placementTemplate, you can update the associated callbackOverrides for the device definition using this API.

projectName
Required: Yes
Type: string

The name of the project to be updated.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalFailureException:

InvalidRequestException:

ResourceNotFoundException:

TooManyRequestsException:

Shapes

DeviceTemplate

Description

An object representing a device for a placement template (see PlacementTemplate).

Members
callbackOverrides
Type: Associative array of custom strings keys (DeviceCallbackKey) to strings

An optional Lambda function to invoke instead of the default Lambda function provided by the placement template.

deviceType
Type: string

The device type, which currently must be "button".

InternalFailureException

Description

Members
code
Required: Yes
Type: string
message
Required: Yes
Type: string

InvalidRequestException

Description

Members
code
Required: Yes
Type: string
message
Required: Yes
Type: string

PlacementDescription

Description

An object describing a project's placement.

Members
attributes
Required: Yes
Type: Associative array of custom strings keys (AttributeName) to strings

The user-defined attributes associated with the placement.

createdDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the placement was initially created, in UNIX epoch time format.

placementName
Required: Yes
Type: string

The name of the placement.

projectName
Required: Yes
Type: string

The name of the project containing the placement.

updatedDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the placement was last updated, in UNIX epoch time format. If the placement was not updated, then createdDate and updatedDate are the same.

PlacementSummary

Description

An object providing summary information for a particular placement.

Members
createdDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the placement was originally created, in UNIX epoch time format.

placementName
Required: Yes
Type: string

The name of the placement being summarized.

projectName
Required: Yes
Type: string

The name of the project containing the placement.

updatedDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the placement was last updated, in UNIX epoch time format. If the placement was not updated, then createdDate and updatedDate are the same.

PlacementTemplate

Description

An object defining the template for a placement.

Members
defaultAttributes
Type: Associative array of custom strings keys (AttributeName) to strings

The default attributes (key/value pairs) to be applied to all placements using this template.

deviceTemplates
Type: Associative array of custom strings keys (DeviceTemplateName) to DeviceTemplate structures

An object specifying the DeviceTemplate for all placements using this (PlacementTemplate) template.

ProjectDescription

Description

An object providing detailed information for a particular project associated with an AWS account and region.

Members
arn
Type: string

The ARN of the project.

createdDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the project was originally created, in UNIX epoch time format.

description
Type: string

The description of the project.

placementTemplate
Type: PlacementTemplate structure

An object describing the project's placement specifications.

projectName
Required: Yes
Type: string

The name of the project for which to obtain information from.

tags
Type: Associative array of custom strings keys (TagKey) to strings

The tags (metadata key/value pairs) associated with the project.

updatedDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the project was last updated, in UNIX epoch time format. If the project was not updated, then createdDate and updatedDate are the same.

ProjectSummary

Description

An object providing summary information for a particular project for an associated AWS account and region.

Members
arn
Type: string

The ARN of the project.

createdDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the project was originally created, in UNIX epoch time format.

projectName
Required: Yes
Type: string

The name of the project being summarized.

tags
Type: Associative array of custom strings keys (TagKey) to strings

The tags (metadata key/value pairs) associated with the project.

updatedDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date when the project was last updated, in UNIX epoch time format. If the project was not updated, then createdDate and updatedDate are the same.

ResourceConflictException

Description

Members
code
Required: Yes
Type: string
message
Required: Yes
Type: string

ResourceNotFoundException

Description

Members
code
Required: Yes
Type: string
message
Required: Yes
Type: string

TooManyRequestsException

Description

Members
code
Required: Yes
Type: string
message
Required: Yes
Type: string