audience_generation_jobs

Creates, updates, deletes, gets or lists an audience_generation_jobs resource.

Overview

Name	audience_generation_jobs
Type	Resource
Id	aws.cleanroomsml.audience_generation_jobs

Fields

The following fields are returned by SELECT queries:

get_audience_generation_job

Name	Datatype	Description
name	string	The name of the audience generation job. (pattern: <code>(?!\s*$)[\u0020-\uD7FF\uE000-\uFFFD\uD800\uDBFF-\uDC00\uDFFF\t]*</code>)
audience_generation_job_arn	string	The Amazon Resource Name (ARN) of the audience generation job. (pattern: <code>arn:aws[-a-z]*:cleanrooms-ml:[-a-z0-9]+:[0-9]{12}:audience-generation-job/[-a-zA-Z0-9_/.]+</code>)
collaboration_id	string	The identifier of the collaboration that this audience generation job is associated with. (pattern: <code>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}</code>)
configured_audience_model_arn	string	The Amazon Resource Name (ARN) of the configured audience model used for this audience generation job. (pattern: <code>arn:aws[-a-z]*:cleanrooms-ml:[-a-z0-9]+:[0-9]{12}:configured-audience-model/[-a-zA-Z0-9_/.]+</code>)
create_time	string (date-time)	The time at which the audience generation job was created.
description	string	The description of the audience generation job. (pattern: <code>[\u0020-\uD7FF\uE000-\uFFFD\uD800\uDBFF-\uDC00\uDFFF\t\r\n]*</code>)
include_seed_in_output	boolean	Configure whether the seed users are included in the output audience. By default, Clean Rooms ML removes seed users from the output audience. If you specify TRUE, the seed users will appear first in the output. Clean Rooms ML does not explicitly reveal whether a user was in the seed, but the recipient of the audience will know that the first minimumSeedSize count of users are from the seed.
metrics	object	The relevance scores for different audience sizes and the recall score of the generated audience.
protected_query_identifier	string	The unique identifier of the protected query for this audience generation job.
seed_audience	object	The seed audience that was used for this audience generation job. This field will be null if the account calling the API is the account that started this audience generation job.
started_by	string	The AWS account that started this audience generation job. (pattern: <code>[0-9]{12}</code>)
status	string	The status of the audience generation job. (CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED, ACTIVE, DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED)
status_details	object	Details about the status of a resource.
tags	object	The tags that are associated to this audience generation job.
update_time	string (date-time)	The most recent time at which the audience generation job was updated.

list_audience_generation_jobs

Name	Datatype	Description
name	string	The name of the audience generation job. (pattern: <code>(?!\s*$)[\u0020-\uD7FF\uE000-\uFFFD\uD800\uDBFF-\uDC00\uDFFF\t]*</code>)
audience_generation_job_arn	string	The Amazon Resource Name (ARN) of the audience generation job. (pattern: <code>arn:aws[-a-z]*:cleanrooms-ml:[-a-z0-9]+:[0-9]{12}:audience-generation-job/[-a-zA-Z0-9_/.]+</code>)
collaboration_id	string	The identifier of the collaboration that contains this audience generation job. (pattern: <code>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}</code>)
configured_audience_model_arn	string	The Amazon Resource Name (ARN) of the configured audience model that was used for this audience generation job. (pattern: <code>arn:aws[-a-z]*:cleanrooms-ml:[-a-z0-9]+:[0-9]{12}:configured-audience-model/[-a-zA-Z0-9_/.]+</code>)
create_time	string (date-time)	The time at which the audience generation job was created.
description	string	The description of the audience generation job. (pattern: <code>[\u0020-\uD7FF\uE000-\uFFFD\uD800\uDBFF-\uDC00\uDFFF\t\r\n]*</code>)
started_by	string	The AWS Account that submitted the job. (pattern: <code>[0-9]{12}</code>)
status	string	The status of the audience generation job. (CREATE_PENDING, CREATE_IN_PROGRESS, CREATE_FAILED, ACTIVE, DELETE_PENDING, DELETE_IN_PROGRESS, DELETE_FAILED)
update_time	string (date-time)	The most recent time at which the audience generation job was updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_audience_generation_job	select	audience_generation_job_arn, region		Returns information about an audience generation job.
list_audience_generation_jobs	select	region	nextToken, maxResults, configuredAudienceModelArn, collaborationId	Returns a list of audience generation jobs.
delete_audience_generation_job	delete	audience_generation_job_arn, region		Deletes the specified audience generation job, and removes all data associated with the job.
start_audience_export_job	exec	region, name, audienceGenerationJobArn, audienceSize		Export an audience of a specified size after you have generated an audience.

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
audience_generation_job_arn	string	The Amazon Resource Name (ARN) of the audience generation job that you want to delete.
region	string	AWS region (default: us-east-1)
collaborationId	string	The identifier of the collaboration that contains the audience generation jobs that you are interested in.
configuredAudienceModelArn	string	The Amazon Resource Name (ARN) of the configured audience model that was used for the audience generation jobs that you are interested in.
maxResults	integer	The maximum size of the results that is returned per call.
nextToken	string	The token value retrieved from a previous call to access the next page of results.

SELECT examples

get_audience_generation_job

Returns information about an audience generation job.

SELECT
name,
audience_generation_job_arn,
collaboration_id,
configured_audience_model_arn,
create_time,
description,
include_seed_in_output,
metrics,
protected_query_identifier,
seed_audience,
started_by,
status,
status_details,
tags,
update_time
FROM aws.cleanroomsml.audience_generation_jobs
WHERE audience_generation_job_arn = '{{ audience_generation_job_arn }}' -- required
AND region = '{{ region }}' -- required
;

list_audience_generation_jobs

Returns a list of audience generation jobs.

SELECT
name,
audience_generation_job_arn,
collaboration_id,
configured_audience_model_arn,
create_time,
description,
started_by,
status,
update_time
FROM aws.cleanroomsml.audience_generation_jobs
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
AND configuredAudienceModelArn = '{{ configuredAudienceModelArn }}'
AND collaborationId = '{{ collaborationId }}'
;

DELETE examples

delete_audience_generation_job

Deletes the specified audience generation job, and removes all data associated with the job.

DELETE FROM aws.cleanroomsml.audience_generation_jobs
WHERE audience_generation_job_arn = '{{ audience_generation_job_arn }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

start_audience_export_job

Export an audience of a specified size after you have generated an audience.

EXEC aws.cleanroomsml.audience_generation_jobs.start_audience_export_job 
@region='{{ region }}' --required 
@@json=
'{
"name": "{{ name }}", 
"audienceGenerationJobArn": "{{ audienceGenerationJobArn }}", 
"audienceSize": "{{ audienceSize }}", 
"description": "{{ description }}"
}'
;