lens

Creates, updates, deletes, gets or lists a lens resource.

Overview

Name	lens
Type	Resource
Id	aws.wellarchitected.lens

Fields

The following fields are returned by SELECT queries:

get_lens

Name	Datatype	Description
description	string	The description of the lens.
lens_arn	string	The ARN of a lens.
lens_version	string	The version of a lens.
name	string	The full name of the lens.
owner	string	The Amazon Web Services account ID that owns the lens.
share_invitation_id	string	The ID assigned to the share invitation. (pattern: <code>[0-9a-f]{32}</code>)
tags	object	The tags assigned to the lens.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_lens	select	lens_alias, region	LensVersion	Get an existing lens.
create_lens_version	insert	lens_alias, region, LensVersion, ClientRequestToken		Create a new lens version. A lens can have up to 100 versions. Use this operation to publish a new lens version after you have imported a lens. The LensAlias is used to identify the lens to be published. The owner of a lens can share the lens with other Amazon Web Services accounts and users in the same Amazon Web Services Region. Only the owner of a lens can delete it.
delete_lens	delete	lens_alias, ClientRequestToken, LensStatus, region		Delete an existing lens. Only the owner of a lens can delete it. After the lens is deleted, Amazon Web Services accounts and users that you shared the lens with can continue to use it, but they will no longer be able to apply it to new workloads. Disclaimer By sharing your custom lenses with other Amazon Web Services accounts, you acknowledge that Amazon Web Services will make your custom lenses available to those other accounts. Those other accounts may continue to access and use your shared custom lenses even if you delete the custom lenses from your own Amazon Web Services account or terminate your Amazon Web Services account.
export_lens	exec	lens_alias, region	LensVersion	Export an existing lens. Only the owner of a lens can export it. Lenses provided by Amazon Web Services (Amazon Web Services Official Content) cannot be exported. Lenses are defined in JSON. For more information, see JSON format specification in the Well-Architected Tool User Guide. Disclaimer Do not include or gather personal identifiable information (PII) of end users or other identifiable individuals in or via your custom lenses. If your custom lens or those shared with you and used in your account do include or collect PII you are responsible for: ensuring that the included PII is processed in accordance with applicable law, providing adequate privacy notices, and obtaining necessary consents for processing such data.
import_lens	exec	region, JSONString, ClientRequestToken		Import a new custom lens or update an existing custom lens. To update an existing custom lens, specify its ARN as the LensAlias. If no ARN is specified, a new custom lens is created. The new or updated lens will have a status of DRAFT. The lens cannot be applied to workloads or shared with other Amazon Web Services accounts until it's published with CreateLensVersion. Lenses are defined in JSON. For more information, see JSON format specification in the Well-Architected Tool User Guide. A custom lens cannot exceed 500 KB in size. Disclaimer Do not include or gather personal identifiable information (PII) of end users or other identifiable individuals in or via your custom lenses. If your custom lens or those shared with you and used in your account do include or collect PII you are responsible for: ensuring that the included PII is processed in accordance with applicable law, providing adequate privacy notices, and obtaining necessary consents for processing such data.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
ClientRequestToken	string
LensStatus	string	The status of the lens to be deleted.
lens_alias	string
region	string	AWS region (default: us-east-1)
LensVersion	string	The lens version to be exported.

SELECT examples

get_lens

Get an existing lens.

SELECT
description,
lens_arn,
lens_version,
name,
owner,
share_invitation_id,
tags
FROM aws.wellarchitected.lens
WHERE lens_alias = '{{ lens_alias }}' -- required
AND region = '{{ region }}' -- required
AND LensVersion = '{{ LensVersion }}'
;

INSERT examples

create_lens_version

Create a new lens version. A lens can have up to 100 versions. Use this operation to publish a new lens version after you have imported a lens. The LensAlias is used to identify the lens to be published. The owner of a lens can share the lens with other Amazon Web Services accounts and users in the same Amazon Web Services Region. Only the owner of a lens can delete it.

INSERT INTO aws.wellarchitected.lens (
LensVersion,
IsMajorVersion,
ClientRequestToken,
lens_alias,
region
)
SELECT 
'{{ LensVersion }}' /* required */,
{{ IsMajorVersion }},
'{{ ClientRequestToken }}' /* required */,
'{{ lens_alias }}',
'{{ region }}'
RETURNING
lens_arn,
lens_version
;

Manifest

# Description fields are for documentation purposes
- name: lens
props:
  - name: lens_alias
    value: "{{ lens_alias }}"
    description: Required parameter for the lens resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the lens resource.
  - name: LensVersion
    value: "{{ LensVersion }}"
  - name: IsMajorVersion
    value: {{ IsMajorVersion }}
  - name: ClientRequestToken
    value: "{{ ClientRequestToken }}"
    description: |
      A unique case-sensitive string used to ensure that this request is idempotent (executes only once). You should not reuse the same token for other requests. If you retry a request with the same client request token and the same parameters after the original request has completed successfully, the result of the original request is returned. This token is listed as required, however, if you do not specify it, the Amazon Web Services SDKs automatically generate one for you. If you are not using the Amazon Web Services SDK or the CLI, you must provide this token or the request will fail.

DELETE examples

delete_lens

Delete an existing lens. Only the owner of a lens can delete it. After the lens is deleted, Amazon Web Services accounts and users that you shared the lens with can continue to use it, but they will no longer be able to apply it to new workloads. Disclaimer By sharing your custom lenses with other Amazon Web Services accounts, you acknowledge that Amazon Web Services will make your custom lenses available to those other accounts. Those other accounts may continue to access and use your shared custom lenses even if you delete the custom lenses from your own Amazon Web Services account or terminate your Amazon Web Services account.

DELETE FROM aws.wellarchitected.lens
WHERE lens_alias = '{{ lens_alias }}' --required
AND ClientRequestToken = '{{ ClientRequestToken }}' --required
AND LensStatus = '{{ LensStatus }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

export_lens

Export an existing lens. Only the owner of a lens can export it. Lenses provided by Amazon Web Services (Amazon Web Services Official Content) cannot be exported. Lenses are defined in JSON. For more information, see JSON format specification in the Well-Architected Tool User Guide. Disclaimer Do not include or gather personal identifiable information (PII) of end users or other identifiable individuals in or via your custom lenses. If your custom lens or those shared with you and used in your account do include or collect PII you are responsible for: ensuring that the included PII is processed in accordance with applicable law, providing adequate privacy notices, and obtaining necessary consents for processing such data.

EXEC aws.wellarchitected.lens.export_lens 
@lens_alias='{{ lens_alias }}' --required, 
@region='{{ region }}' --required, 
@LensVersion='{{ LensVersion }}'
;

import_lens

Import a new custom lens or update an existing custom lens. To update an existing custom lens, specify its ARN as the LensAlias. If no ARN is specified, a new custom lens is created. The new or updated lens will have a status of DRAFT. The lens cannot be applied to workloads or shared with other Amazon Web Services accounts until it's published with CreateLensVersion. Lenses are defined in JSON. For more information, see JSON format specification in the Well-Architected Tool User Guide. A custom lens cannot exceed 500 KB in size. Disclaimer Do not include or gather personal identifiable information (PII) of end users or other identifiable individuals in or via your custom lenses. If your custom lens or those shared with you and used in your account do include or collect PII you are responsible for: ensuring that the included PII is processed in accordance with applicable law, providing adequate privacy notices, and obtaining necessary consents for processing such data.

EXEC aws.wellarchitected.lens.import_lens 
@region='{{ region }}' --required 
@@json=
'{
"LensAlias": "{{ LensAlias }}", 
"JSONString": "{{ JSONString }}", 
"ClientRequestToken": "{{ ClientRequestToken }}", 
"Tags": "{{ Tags }}"
}'
;