cleanrooms-ml

2023/11/29 - cleanrooms-ml - 25 new api methods

Changes  Public Preview SDK release of AWS Clean Rooms ML APIs

PutConfiguredAudienceModelPolicy (new) Link ¶

Create or update the resource policy for a configured audience model.

See also: AWS API Documentation

Request Syntax

client.put_configured_audience_model_policy(
    configuredAudienceModelArn='string',
    configuredAudienceModelPolicy='string',
    policyExistenceCondition='POLICY_MUST_EXIST'|'POLICY_MUST_NOT_EXIST',
    previousPolicyHash='string'
)
type configuredAudienceModelArn

string

param configuredAudienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the configured audience model that the resource policy will govern.

type configuredAudienceModelPolicy

string

param configuredAudienceModelPolicy

[REQUIRED]

The IAM resource policy.

type policyExistenceCondition

string

param policyExistenceCondition

Use this to prevent unexpected concurrent modification of the policy.

type previousPolicyHash

string

param previousPolicyHash

A cryptographic hash of the contents of the policy used to prevent unexpected concurrent modification of the policy.

rtype

dict

returns

Response Syntax

{
    'configuredAudienceModelPolicy': 'string',
    'policyHash': 'string'
}

Response Structure

  • (dict) --

    • configuredAudienceModelPolicy (string) --

      The IAM resource policy.

    • policyHash (string) --

      A cryptographic hash of the contents of the policy used to prevent unexpected concurrent modification of the policy.

ListAudienceExportJobs (new) Link ¶

Returns a list of the audience export jobs.

See also: AWS API Documentation

Request Syntax

client.list_audience_export_jobs(
    audienceGenerationJobArn='string',
    maxResults=123,
    nextToken='string'
)
type audienceGenerationJobArn

string

param audienceGenerationJobArn

The Amazon Resource Name (ARN) of the audience generation job that you are interested in.

type maxResults

integer

param maxResults

The maximum size of the results that is returned per call.

type nextToken

string

param nextToken

The token value retrieved from a previous call to access the next page of results.

rtype

dict

returns

Response Syntax

{
    'audienceExportJobs': [
        {
            'audienceGenerationJobArn': 'string',
            'audienceSize': {
                'type': 'ABSOLUTE'|'PERCENTAGE',
                'value': 123
            },
            'createTime': datetime(2015, 1, 1),
            'description': 'string',
            'name': 'string',
            'outputLocation': 'string',
            'status': 'CREATE_PENDING'|'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'ACTIVE',
            'statusDetails': {
                'message': 'string',
                'statusCode': 'string'
            },
            'updateTime': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • audienceExportJobs (list) --

      The audience export jobs that match the request.

      • (dict) --

        Provides information about the audience export job.

        • audienceGenerationJobArn (string) --

          The Amazon Resource Name (ARN) of the audience generation job that was exported.

        • audienceSize (dict) --

          The size of the generated audience. Must match one of the sizes in the configured audience model.

          • type (string) --

            Whether the audience size is defined in absolute terms or as a percentage. You can use the ABSOLUTE AudienceSize to configure out audience sizes using the count of identifiers in the output. You can use the Percentage AudienceSize to configure sizes in the range 1-100 percent.

          • value (integer) --

            Specify an audience size value.

        • createTime (datetime) --

          The time at which the audience export job was created.

        • description (string) --

          The description of the audience export job.

        • name (string) --

          The name of the audience export job.

        • outputLocation (string) --

          The Amazon S3 bucket where the audience export is stored.

        • status (string) --

          The status of the audience export job.

        • statusDetails (dict) --

          Details about the status of a resource.

          • message (string) --

            The error message that was returned. The message is intended for human consumption and can change at any time. Use the statusCode for programmatic error handling.

          • statusCode (string) --

            The status code that was returned. The status code is intended for programmatic error handling. Clean Rooms ML will not change the status code for existing error conditions.

        • updateTime (datetime) --

          The most recent time at which the audience export job was updated.

    • nextToken (string) --

      The token value retrieved from a previous call to access the next page of results.

CreateAudienceModel (new) Link ¶

Defines the information necessary to create an audience model. An audience model is a machine learning model that Clean Rooms ML trains to measure similarity between users. Clean Rooms ML manages training and storing the audience model. The audience model can be used in multiple calls to the StartAudienceGenerationJob API.

See also: AWS API Documentation

Request Syntax

client.create_audience_model(
    description='string',
    kmsKeyArn='string',
    name='string',
    tags={
        'string': 'string'
    },
    trainingDataEndTime=datetime(2015, 1, 1),
    trainingDataStartTime=datetime(2015, 1, 1),
    trainingDatasetArn='string'
)
type description

string

param description

The description of the audience model.

type kmsKeyArn

string

param kmsKeyArn

The Amazon Resource Name (ARN) of the KMS key. This key is used to encrypt and decrypt customer-owned data in the trained ML model and the associated data.

type name

string

param name

[REQUIRED]

The name of the audience model resource.

type tags

dict

param tags

The optional metadata that you apply to the resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.

The following basic restrictions apply to tags:

  • Maximum number of tags per resource - 50.

  • For each resource, each tag key must be unique, and each tag key can have only one value.

  • Maximum key length - 128 Unicode characters in UTF-8.

  • Maximum value length - 256 Unicode characters in UTF-8.

  • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

  • Tag keys and values are case sensitive.

  • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Forecast considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.

  • (string) --

    • (string) --

type trainingDataEndTime

datetime

param trainingDataEndTime

The end date and time of the training window.

type trainingDataStartTime

datetime

param trainingDataStartTime

The start date and time of the training window.

type trainingDatasetArn

string

param trainingDatasetArn

[REQUIRED]

The Amazon Resource Name (ARN) of the training dataset for this audience model.

rtype

dict

returns

Response Syntax

{
    'audienceModelArn': 'string'
}

Response Structure

  • (dict) --

    • audienceModelArn (string) --

      The Amazon Resource Name (ARN) of the audience model.

CreateConfiguredAudienceModel (new) Link ¶

Defines the information necessary to create a configured audience model.

See also: AWS API Documentation

Request Syntax

client.create_configured_audience_model(
    audienceModelArn='string',
    audienceSizeConfig={
        'audienceSizeBins': [
            123,
        ],
        'audienceSizeType': 'ABSOLUTE'|'PERCENTAGE'
    },
    childResourceTagOnCreatePolicy='FROM_PARENT_RESOURCE'|'NONE',
    description='string',
    minMatchingSeedSize=123,
    name='string',
    outputConfig={
        'destination': {
            's3Destination': {
                's3Uri': 'string'
            }
        },
        'roleArn': 'string'
    },
    sharedAudienceMetrics=[
        'ALL'|'NONE',
    ],
    tags={
        'string': 'string'
    }
)
type audienceModelArn

string

param audienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the audience model to use for the configured audience model.

type audienceSizeConfig

dict

param audienceSizeConfig

Configure the list of output sizes of audiences that can be created using this configured audience model. A request to StartAudienceGenerationJob that uses this configured audience model must have an audienceSize selected from this list. You can use the ABSOLUTE AudienceSize to configure out audience sizes using the count of identifiers in the output. You can use the Percentage AudienceSize to configure sizes in the range 1-100 percent.

  • audienceSizeBins (list) -- [REQUIRED]

    An array of the different audience output sizes.

    • (integer) --

  • audienceSizeType (string) -- [REQUIRED]

    Whether the audience output sizes are defined as an absolute number or a percentage.

type childResourceTagOnCreatePolicy

string

param childResourceTagOnCreatePolicy

Configure how the service tags audience generation jobs created using this configured audience model. If you specify NONE , the tags from the StartAudienceGenerationJob request determine the tags of the audience generation job. If you specify FROM_PARENT_RESOURCE , the audience generation job inherits the tags from the configured audience model, by default. Tags in the StartAudienceGenerationJob will override the default.

type description

string

param description

The description of the configured audience model.

type minMatchingSeedSize

integer

param minMatchingSeedSize

The minimum number of users from the seed audience that must match with users in the training data of the audience model.

type name

string

param name

[REQUIRED]

The name of the configured audience model.

type outputConfig

dict

param outputConfig

[REQUIRED]

Configure the Amazon S3 location and IAM Role for audiences created using this configured audience model. Each audience will have a unique location. The IAM Role must have s3:PutObject permission on the destination Amazon S3 location. If the destination is protected with Amazon S3 KMS-SSE, then the Role must also have the required KMS permissions.

  • destination (dict) -- [REQUIRED]

    Defines the Amazon S3 bucket where the configured audience is stored.

    • s3Destination (dict) -- [REQUIRED]

      The Amazon S3 bucket and path for the configured audience.

      • s3Uri (string) -- [REQUIRED]

        The Amazon S3 location URI.

  • roleArn (string) -- [REQUIRED]

    The ARN of the IAM role that can write the Amazon S3 bucket.

type sharedAudienceMetrics

list

param sharedAudienceMetrics

[REQUIRED]

Whether audience metrics are shared.

  • (string) --

type tags

dict

param tags

The optional metadata that you apply to the resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.

The following basic restrictions apply to tags:

  • Maximum number of tags per resource - 50.

  • For each resource, each tag key must be unique, and each tag key can have only one value.

  • Maximum key length - 128 Unicode characters in UTF-8.

  • Maximum value length - 256 Unicode characters in UTF-8.

  • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

  • Tag keys and values are case sensitive.

  • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Forecast considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.

  • (string) --

    • (string) --

rtype

dict

returns

Response Syntax

{
    'configuredAudienceModelArn': 'string'
}

Response Structure

  • (dict) --

    • configuredAudienceModelArn (string) --

      The Amazon Resource Name (ARN) of the configured audience model.

UpdateConfiguredAudienceModel (new) Link ¶

Provides the information necessary to update a configured audience model. Updates that impact audience generation jobs take effect when a new job starts, but do not impact currently running jobs.

See also: AWS API Documentation

Request Syntax

client.update_configured_audience_model(
    audienceModelArn='string',
    audienceSizeConfig={
        'audienceSizeBins': [
            123,
        ],
        'audienceSizeType': 'ABSOLUTE'|'PERCENTAGE'
    },
    configuredAudienceModelArn='string',
    description='string',
    minMatchingSeedSize=123,
    outputConfig={
        'destination': {
            's3Destination': {
                's3Uri': 'string'
            }
        },
        'roleArn': 'string'
    },
    sharedAudienceMetrics=[
        'ALL'|'NONE',
    ]
)
type audienceModelArn

string

param audienceModelArn

The Amazon Resource Name (ARN) of the new audience model that you want to use.

type audienceSizeConfig

dict

param audienceSizeConfig

The new audience size configuration.

  • audienceSizeBins (list) -- [REQUIRED]

    An array of the different audience output sizes.

    • (integer) --

  • audienceSizeType (string) -- [REQUIRED]

    Whether the audience output sizes are defined as an absolute number or a percentage.

type configuredAudienceModelArn

string

param configuredAudienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the configured audience model that you want to update.

type description

string

param description

The new description of the configured audience model.

type minMatchingSeedSize

integer

param minMatchingSeedSize

The minimum number of users from the seed audience that must match with users in the training data of the audience model.

type outputConfig

dict

param outputConfig

The new output configuration.

  • destination (dict) -- [REQUIRED]

    Defines the Amazon S3 bucket where the configured audience is stored.

    • s3Destination (dict) -- [REQUIRED]

      The Amazon S3 bucket and path for the configured audience.

      • s3Uri (string) -- [REQUIRED]

        The Amazon S3 location URI.

  • roleArn (string) -- [REQUIRED]

    The ARN of the IAM role that can write the Amazon S3 bucket.

type sharedAudienceMetrics

list

param sharedAudienceMetrics

The new value for whether to share audience metrics.

  • (string) --

rtype

dict

returns

Response Syntax

{
    'configuredAudienceModelArn': 'string'
}

Response Structure

  • (dict) --

    • configuredAudienceModelArn (string) --

      The Amazon Resource Name (ARN) of the configured audience model that was updated.

GetConfiguredAudienceModelPolicy (new) Link ¶

Returns information about a configured audience model policy.

See also: AWS API Documentation

Request Syntax

client.get_configured_audience_model_policy(
    configuredAudienceModelArn='string'
)
type configuredAudienceModelArn

string

param configuredAudienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the configured audience model that you are interested in.

rtype

dict

returns

Response Syntax

{
    'configuredAudienceModelArn': 'string',
    'configuredAudienceModelPolicy': 'string',
    'policyHash': 'string'
}

Response Structure

  • (dict) --

    • configuredAudienceModelArn (string) --

      The Amazon Resource Name (ARN) of the configured audience model.

    • configuredAudienceModelPolicy (string) --

      The configured audience model policy. This is a JSON IAM resource policy.

    • policyHash (string) --

      A cryptographic hash of the contents of the policy used to prevent unexpected concurrent modification of the policy.

DeleteAudienceModel (new) Link ¶

Specifies an audience model that you want to delete. You can't delete an audience model if there are any configured audience models that depend on the audience model.

See also: AWS API Documentation

Request Syntax

client.delete_audience_model(
    audienceModelArn='string'
)
type audienceModelArn

string

param audienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the audience model that you want to delete.

returns

None

GetTrainingDataset (new) Link ¶

Returns information about a training dataset.

See also: AWS API Documentation

Request Syntax

client.get_training_dataset(
    trainingDatasetArn='string'
)
type trainingDatasetArn

string

param trainingDatasetArn

[REQUIRED]

The Amazon Resource Name (ARN) of the training dataset that you are interested in.

rtype

dict

returns

Response Syntax

{
    'createTime': datetime(2015, 1, 1),
    'description': 'string',
    'name': 'string',
    'roleArn': 'string',
    'status': 'ACTIVE',
    'tags': {
        'string': 'string'
    },
    'trainingData': [
        {
            'inputConfig': {
                'dataSource': {
                    'glueDataSource': {
                        'catalogId': 'string',
                        'databaseName': 'string',
                        'tableName': 'string'
                    }
                },
                'schema': [
                    {
                        'columnName': 'string',
                        'columnTypes': [
                            'USER_ID'|'ITEM_ID'|'TIMESTAMP'|'CATEGORICAL_FEATURE'|'NUMERICAL_FEATURE',
                        ]
                    },
                ]
            },
            'type': 'INTERACTIONS'
        },
    ],
    'trainingDatasetArn': 'string',
    'updateTime': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • createTime (datetime) --

      The time at which the training dataset was created.

    • description (string) --

      The description of the training dataset.

    • name (string) --

      The name of the training dataset.

    • roleArn (string) --

      The IAM role used to read the training data.

    • status (string) --

      The status of the training dataset.

    • tags (dict) --

      The tags that are assigned to this training dataset.

      • (string) --

        • (string) --

    • trainingData (list) --

      Metadata about the requested training data.

      • (dict) --

        Defines where the training dataset is located, what type of data it contains, and how to access the data.

        • inputConfig (dict) --

          A DatasetInputConfig object that defines the data source and schema mapping.

          • dataSource (dict) --

            A DataSource object that specifies the Glue data source for the training data.

            • glueDataSource (dict) --

              A GlueDataSource object that defines the catalog ID, database name, and table name for the training data.

              • catalogId (string) --

                The Glue catalog that contains the training data.

              • databaseName (string) --

                The Glue database that contains the training data.

              • tableName (string) --

                The Glue table that contains the training data.

          • schema (list) --

            The schema information for the training data.

            • (dict) --

              Metadata for a column.

              • columnName (string) --

                The name of a column.

              • columnTypes (list) --

                The data type of column.

                • (string) --

        • type (string) --

          What type of information is found in the dataset.

    • trainingDatasetArn (string) --

      The Amazon Resource Name (ARN) of the training dataset.

    • updateTime (datetime) --

      The most recent time at which the training dataset was updated.

DeleteConfiguredAudienceModelPolicy (new) Link ¶

Deletes the specified configured audience model policy.

See also: AWS API Documentation

Request Syntax

client.delete_configured_audience_model_policy(
    configuredAudienceModelArn='string'
)
type configuredAudienceModelArn

string

param configuredAudienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the configured audience model policy that you want to delete.

returns

None

ListAudienceGenerationJobs (new) Link ¶

Returns a list of audience generation jobs.

See also: AWS API Documentation

Request Syntax

client.list_audience_generation_jobs(
    collaborationId='string',
    configuredAudienceModelArn='string',
    maxResults=123,
    nextToken='string'
)
type collaborationId

string

param collaborationId

The identifier of the collaboration that contains the audience generation jobs that you are interested in.

type configuredAudienceModelArn

string

param configuredAudienceModelArn

The Amazon Resource Name (ARN) of the configured audience model that was used for the audience generation jobs that you are interested in.

type maxResults

integer

param maxResults

The maximum size of the results that is returned per call.

type nextToken

string

param nextToken

The token value retrieved from a previous call to access the next page of results.

rtype

dict

returns

Response Syntax

{
    'audienceGenerationJobs': [
        {
            'audienceGenerationJobArn': 'string',
            'collaborationId': 'string',
            'configuredAudienceModelArn': 'string',
            'createTime': datetime(2015, 1, 1),
            'description': 'string',
            'name': 'string',
            'startedBy': 'string',
            'status': 'CREATE_PENDING'|'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'ACTIVE'|'DELETE_PENDING'|'DELETE_IN_PROGRESS'|'DELETE_FAILED',
            'updateTime': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • audienceGenerationJobs (list) --

      The audience generation jobs that match the request.

      • (dict) --

        Provides information about the configured audience generation job.

        • audienceGenerationJobArn (string) --

          The Amazon Resource Name (ARN) of the audience generation job.

        • collaborationId (string) --

          The identifier of the collaboration that contains this audience generation job.

        • configuredAudienceModelArn (string) --

          The Amazon Resource Name (ARN) of the configured audience model that was used for this audience generation job.

        • createTime (datetime) --

          The time at which the audience generation job was created.

        • description (string) --

          The description of the audience generation job.

        • name (string) --

          The name of the audience generation job.

        • startedBy (string) --

          The AWS Account that submitted the job.

        • status (string) --

          The status of the audience generation job.

        • updateTime (datetime) --

          The most recent time at which the audience generation job was updated.

    • nextToken (string) --

      The token value retrieved from a previous call to access the next page of results.

StartAudienceGenerationJob (new) Link ¶

Information necessary to start the audience generation job.

See also: AWS API Documentation

Request Syntax

client.start_audience_generation_job(
    collaborationId='string',
    configuredAudienceModelArn='string',
    description='string',
    includeSeedInOutput=True|False,
    name='string',
    seedAudience={
        'dataSource': {
            's3Uri': 'string'
        },
        'roleArn': 'string'
    },
    tags={
        'string': 'string'
    }
)
type collaborationId

string

param collaborationId

The identifier of the collaboration that contains the audience generation job.

type configuredAudienceModelArn

string

param configuredAudienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the configured audience model that is used for this audience generation job.

type description

string

param description

The description of the audience generation job.

type includeSeedInOutput

boolean

param includeSeedInOutput

Whether the seed audience is included in the audience generation output.

type name

string

param name

[REQUIRED]

The name of the audience generation job.

type seedAudience

dict

param seedAudience

[REQUIRED]

The seed audience that is used to generate the audience.

  • dataSource (dict) -- [REQUIRED]

    The Amazon S3 bucket where the training data for the configured audience is stored.

    • s3Uri (string) -- [REQUIRED]

      The Amazon S3 location URI.

  • roleArn (string) -- [REQUIRED]

    The ARN of the IAM role that can read the Amazon S3 bucket where the training data is stored.

type tags

dict

param tags

The optional metadata that you apply to the resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.

The following basic restrictions apply to tags:

  • Maximum number of tags per resource - 50.

  • For each resource, each tag key must be unique, and each tag key can have only one value.

  • Maximum key length - 128 Unicode characters in UTF-8.

  • Maximum value length - 256 Unicode characters in UTF-8.

  • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

  • Tag keys and values are case sensitive.

  • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Forecast considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.

  • (string) --

    • (string) --

rtype

dict

returns

Response Syntax

{
    'audienceGenerationJobArn': 'string'
}

Response Structure

  • (dict) --

    • audienceGenerationJobArn (string) --

      The Amazon Resource Name (ARN) of the audience generation job.

ListTagsForResource (new) Link ¶

Returns a list of tags for a provided resource.

See also: AWS API Documentation

Request Syntax

client.list_tags_for_resource(
    resourceArn='string'
)
type resourceArn

string

param resourceArn

[REQUIRED]

The Amazon Resource Name (ARN) of the resource that you are interested in.

rtype

dict

returns

Response Syntax

{
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) --

    • tags (dict) --

      The tags that are associated with the resource.

      • (string) --

        • (string) --

ListTrainingDatasets (new) Link ¶

Returns a list of training datasets.

See also: AWS API Documentation

Request Syntax

client.list_training_datasets(
    maxResults=123,
    nextToken='string'
)
type maxResults

integer

param maxResults

The maximum size of the results that is returned per call.

type nextToken

string

param nextToken

The token value retrieved from a previous call to access the next page of results.

rtype

dict

returns

Response Syntax

{
    'nextToken': 'string',
    'trainingDatasets': [
        {
            'createTime': datetime(2015, 1, 1),
            'description': 'string',
            'name': 'string',
            'status': 'ACTIVE',
            'trainingDatasetArn': 'string',
            'updateTime': datetime(2015, 1, 1)
        },
    ]
}

Response Structure

  • (dict) --

    • nextToken (string) --

      The token value retrieved from a previous call to access the next page of results.

    • trainingDatasets (list) --

      The training datasets that match the request.

      • (dict) --

        Provides information about the training dataset.

        • createTime (datetime) --

          The time at which the training dataset was created.

        • description (string) --

          The description of the training dataset.

        • name (string) --

          The name of the training dataset.

        • status (string) --

          The status of the training dataset.

        • trainingDatasetArn (string) --

          The Amazon Resource Name (ARN) of the training dataset.

        • updateTime (datetime) --

          The most recent time at which the training dataset was updated.

ListConfiguredAudienceModels (new) Link ¶

Returns a list of the configured audience models.

See also: AWS API Documentation

Request Syntax

client.list_configured_audience_models(
    maxResults=123,
    nextToken='string'
)
type maxResults

integer

param maxResults

The maximum size of the results that is returned per call.

type nextToken

string

param nextToken

The token value retrieved from a previous call to access the next page of results.

rtype

dict

returns

Response Syntax

{
    'configuredAudienceModels': [
        {
            'audienceModelArn': 'string',
            'configuredAudienceModelArn': 'string',
            'createTime': datetime(2015, 1, 1),
            'description': 'string',
            'name': 'string',
            'outputConfig': {
                'destination': {
                    's3Destination': {
                        's3Uri': 'string'
                    }
                },
                'roleArn': 'string'
            },
            'status': 'ACTIVE',
            'updateTime': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • configuredAudienceModels (list) --

      The configured audience models.

      • (dict) --

        Information about the configured audience model.

        • audienceModelArn (string) --

          The Amazon Resource Name (ARN) of the audience model that was used to create the configured audience model.

        • configuredAudienceModelArn (string) --

          The Amazon Resource Name (ARN) of the configured audience model that you are interested in.

        • createTime (datetime) --

          The time at which the configured audience model was created.

        • description (string) --

          The description of the configured audience model.

        • name (string) --

          The name of the configured audience model.

        • outputConfig (dict) --

          The output configuration of the configured audience model.

          • destination (dict) --

            Defines the Amazon S3 bucket where the configured audience is stored.

            • s3Destination (dict) --

              The Amazon S3 bucket and path for the configured audience.

              • s3Uri (string) --

                The Amazon S3 location URI.

          • roleArn (string) --

            The ARN of the IAM role that can write the Amazon S3 bucket.

        • status (string) --

          The status of the configured audience model.

        • updateTime (datetime) --

          The most recent time at which the configured audience model was updated.

    • nextToken (string) --

      The token value retrieved from a previous call to access the next page of results.

TagResource (new) Link ¶

Adds metadata tags to a specified resource.

See also: AWS API Documentation

Request Syntax

client.tag_resource(
    resourceArn='string',
    tags={
        'string': 'string'
    }
)
type resourceArn

string

param resourceArn

[REQUIRED]

The Amazon Resource Name (ARN) of the resource that you want to assign tags.

type tags

dict

param tags

[REQUIRED]

The optional metadata that you apply to the resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.

The following basic restrictions apply to tags:

  • Maximum number of tags per resource - 50.

  • For each resource, each tag key must be unique, and each tag key can have only one value.

  • Maximum key length - 128 Unicode characters in UTF-8.

  • Maximum value length - 256 Unicode characters in UTF-8.

  • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

  • Tag keys and values are case sensitive.

  • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Forecast considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.

  • (string) --

    • (string) --

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

DeleteAudienceGenerationJob (new) Link ¶

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

See also: AWS API Documentation

Request Syntax

client.delete_audience_generation_job(
    audienceGenerationJobArn='string'
)
type audienceGenerationJobArn

string

param audienceGenerationJobArn

[REQUIRED]

The Amazon Resource Name (ARN) of the audience generation job that you want to delete.

returns

None

UntagResource (new) Link ¶

Removes metadata tags from a specified resource.

See also: AWS API Documentation

Request Syntax

client.untag_resource(
    resourceArn='string',
    tagKeys=[
        'string',
    ]
)
type resourceArn

string

param resourceArn

[REQUIRED]

The Amazon Resource Name (ARN) of the resource that you want to remove tags from.

type tagKeys

list

param tagKeys

[REQUIRED]

The key values of tags that you want to remove.

  • (string) --

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

DeleteTrainingDataset (new) Link ¶

Specifies a training dataset that you want to delete. You can't delete a training dataset if there are any audience models that depend on the training dataset. In Clean Rooms ML, the TrainingDataset is metadata that points to a Glue table, which is read only during AudienceModel creation. This action deletes the metadata.

See also: AWS API Documentation

Request Syntax

client.delete_training_dataset(
    trainingDatasetArn='string'
)
type trainingDatasetArn

string

param trainingDatasetArn

[REQUIRED]

The Amazon Resource Name (ARN) of the training dataset that you want to delete.

returns

None

ListAudienceModels (new) Link ¶

Returns a list of audience models.

See also: AWS API Documentation

Request Syntax

client.list_audience_models(
    maxResults=123,
    nextToken='string'
)
type maxResults

integer

param maxResults

The maximum size of the results that is returned per call.

type nextToken

string

param nextToken

The token value retrieved from a previous call to access the next page of results.

rtype

dict

returns

Response Syntax

{
    'audienceModels': [
        {
            'audienceModelArn': 'string',
            'createTime': datetime(2015, 1, 1),
            'description': 'string',
            'name': 'string',
            'status': 'CREATE_PENDING'|'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'ACTIVE'|'DELETE_PENDING'|'DELETE_IN_PROGRESS'|'DELETE_FAILED',
            'trainingDatasetArn': 'string',
            'updateTime': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • audienceModels (list) --

      The audience models that match the request.

      • (dict) --

        Information about the audience model.

        • audienceModelArn (string) --

          The Amazon Resource Name (ARN) of the audience model.

        • createTime (datetime) --

          The time at which the audience model was created.

        • description (string) --

          The description of the audience model.

        • name (string) --

          The name of the audience model.

        • status (string) --

          The status of the audience model.

        • trainingDatasetArn (string) --

          The Amazon Resource Name (ARN) of the training dataset that was used for the audience model.

        • updateTime (datetime) --

          The most recent time at which the audience model was updated.

    • nextToken (string) --

      The token value retrieved from a previous call to access the next page of results.

DeleteConfiguredAudienceModel (new) Link ¶

Deletes the specified configured audience model. You can't delete a configured audience model if there are any lookalike models that use the configured audience model. If you delete a configured audience model, it will be removed from any collaborations that it is associated to.

See also: AWS API Documentation

Request Syntax

client.delete_configured_audience_model(
    configuredAudienceModelArn='string'
)
type configuredAudienceModelArn

string

param configuredAudienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the configured audience model that you want to delete.

returns

None

GetAudienceModel (new) Link ¶

Returns information about an audience model

See also: AWS API Documentation

Request Syntax

client.get_audience_model(
    audienceModelArn='string'
)
type audienceModelArn

string

param audienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the audience model that you are interested in.

rtype

dict

returns

Response Syntax

{
    'audienceModelArn': 'string',
    'createTime': datetime(2015, 1, 1),
    'description': 'string',
    'kmsKeyArn': 'string',
    'metrics': [
        {
            'forTopKItemPredictions': 123,
            'type': 'NORMALIZED_DISCOUNTED_CUMULATIVE_GAIN'|'MEAN_RECIPROCAL_RANK'|'PRECISION'|'RECALL',
            'value': 123.0
        },
    ],
    'name': 'string',
    'status': 'CREATE_PENDING'|'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'ACTIVE'|'DELETE_PENDING'|'DELETE_IN_PROGRESS'|'DELETE_FAILED',
    'statusDetails': {
        'message': 'string',
        'statusCode': 'string'
    },
    'tags': {
        'string': 'string'
    },
    'trainingDataEndTime': datetime(2015, 1, 1),
    'trainingDataStartTime': datetime(2015, 1, 1),
    'trainingDatasetArn': 'string',
    'updateTime': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • audienceModelArn (string) --

      The Amazon Resource Name (ARN) of the audience model.

    • createTime (datetime) --

      The time at which the audience model was created.

    • description (string) --

      The description of the audience model.

    • kmsKeyArn (string) --

      The KMS key ARN used for the audience model.

    • metrics (list) --

      Accuracy metrics for the model.

      • (dict) --

        The audience model metrics.

        • forTopKItemPredictions (integer) --

          The number of users that were used to generate these model metrics.

        • type (string) --

          The audience model metric.

        • value (float) --

          The value of the audience model metric

    • name (string) --

      The name of the audience model.

    • status (string) --

      The status of the audience model.

    • statusDetails (dict) --

      Details about the status of the audience model.

      • message (string) --

        The error message that was returned. The message is intended for human consumption and can change at any time. Use the statusCode for programmatic error handling.

      • statusCode (string) --

        The status code that was returned. The status code is intended for programmatic error handling. Clean Rooms ML will not change the status code for existing error conditions.

    • tags (dict) --

      The tags that are assigned to the audience model.

      • (string) --

        • (string) --

    • trainingDataEndTime (datetime) --

      The end date specified for the training window.

    • trainingDataStartTime (datetime) --

      The start date specified for the training window.

    • trainingDatasetArn (string) --

      The Amazon Resource Name (ARN) of the training dataset that was used for this audience model.

    • updateTime (datetime) --

      The most recent time at which the audience model was updated.

GetConfiguredAudienceModel (new) Link ¶

Returns information about a specified configured audience model.

See also: AWS API Documentation

Request Syntax

client.get_configured_audience_model(
    configuredAudienceModelArn='string'
)
type configuredAudienceModelArn

string

param configuredAudienceModelArn

[REQUIRED]

The Amazon Resource Name (ARN) of the configured audience model that you are interested in.

rtype

dict

returns

Response Syntax

{
    'audienceModelArn': 'string',
    'audienceSizeConfig': {
        'audienceSizeBins': [
            123,
        ],
        'audienceSizeType': 'ABSOLUTE'|'PERCENTAGE'
    },
    'childResourceTagOnCreatePolicy': 'FROM_PARENT_RESOURCE'|'NONE',
    'configuredAudienceModelArn': 'string',
    'createTime': datetime(2015, 1, 1),
    'description': 'string',
    'minMatchingSeedSize': 123,
    'name': 'string',
    'outputConfig': {
        'destination': {
            's3Destination': {
                's3Uri': 'string'
            }
        },
        'roleArn': 'string'
    },
    'sharedAudienceMetrics': [
        'ALL'|'NONE',
    ],
    'status': 'ACTIVE',
    'tags': {
        'string': 'string'
    },
    'updateTime': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • audienceModelArn (string) --

      The Amazon Resource Name (ARN) of the audience model used for this configured audience model.

    • audienceSizeConfig (dict) --

      The list of output sizes of audiences that can be created using this configured audience model. A request to StartAudienceGenerationJob that uses this configured audience model must have an audienceSize selected from this list. You can use the ABSOLUTE AudienceSize to configure out audience sizes using the count of identifiers in the output. You can use the Percentage AudienceSize to configure sizes in the range 1-100 percent.

      • audienceSizeBins (list) --

        An array of the different audience output sizes.

        • (integer) --

      • audienceSizeType (string) --

        Whether the audience output sizes are defined as an absolute number or a percentage.

    • childResourceTagOnCreatePolicy (string) --

      Provides the childResourceTagOnCreatePolicy that was used for this configured audience model.

    • configuredAudienceModelArn (string) --

      The Amazon Resource Name (ARN) of the configured audience model.

    • createTime (datetime) --

      The time at which the configured audience model was created.

    • description (string) --

      The description of the configured audience model.

    • minMatchingSeedSize (integer) --

      The minimum number of users from the seed audience that must match with users in the training data of the audience model.

    • name (string) --

      The name of the configured audience model.

    • outputConfig (dict) --

      The output configuration of the configured audience model

      • destination (dict) --

        Defines the Amazon S3 bucket where the configured audience is stored.

        • s3Destination (dict) --

          The Amazon S3 bucket and path for the configured audience.

          • s3Uri (string) --

            The Amazon S3 location URI.

      • roleArn (string) --

        The ARN of the IAM role that can write the Amazon S3 bucket.

    • sharedAudienceMetrics (list) --

      Whether audience metrics are shared.

      • (string) --

    • status (string) --

      The status of the configured audience model.

    • tags (dict) --

      The tags that are associated to this configured audience model.

      • (string) --

        • (string) --

    • updateTime (datetime) --

      The most recent time at which the configured audience model was updated.

CreateTrainingDataset (new) Link ¶

Defines the information necessary to create a training dataset, or seed audience. In Clean Rooms ML, the TrainingDataset is metadata that points to a Glue table, which is read only during AudienceModel creation.

See also: AWS API Documentation

Request Syntax

client.create_training_dataset(
    description='string',
    name='string',
    roleArn='string',
    tags={
        'string': 'string'
    },
    trainingData=[
        {
            'inputConfig': {
                'dataSource': {
                    'glueDataSource': {
                        'catalogId': 'string',
                        'databaseName': 'string',
                        'tableName': 'string'
                    }
                },
                'schema': [
                    {
                        'columnName': 'string',
                        'columnTypes': [
                            'USER_ID'|'ITEM_ID'|'TIMESTAMP'|'CATEGORICAL_FEATURE'|'NUMERICAL_FEATURE',
                        ]
                    },
                ]
            },
            'type': 'INTERACTIONS'
        },
    ]
)
type description

string

param description

The description of the training dataset.

type name

string

param name

[REQUIRED]

The name of the training dataset. This name must be unique in your account and region.

type roleArn

string

param roleArn

[REQUIRED]

The ARN of the IAM role that Clean Rooms ML can assume to read the data referred to in the dataSource field of each dataset.

Passing a role across AWS accounts is not allowed. If you pass a role that isn't in your account, you get an AccessDeniedException error.

type tags

dict

param tags

The optional metadata that you apply to the resource to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.

The following basic restrictions apply to tags:

  • Maximum number of tags per resource - 50.

  • For each resource, each tag key must be unique, and each tag key can have only one value.

  • Maximum key length - 128 Unicode characters in UTF-8.

  • Maximum value length - 256 Unicode characters in UTF-8.

  • If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

  • Tag keys and values are case sensitive.

  • Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for keys as it is reserved for AWS use. You cannot edit or delete tag keys with this prefix. Values can have this prefix. If a tag value has aws as its prefix but the key does not, then Clean Rooms ML considers it to be a user tag and will count against the limit of 50 tags. Tags with only the key prefix of aws do not count against your tags per resource limit.

  • (string) --

    • (string) --

type trainingData

list

param trainingData

[REQUIRED]

An array of information that lists the Dataset objects, which specifies the dataset type and details on its location and schema. You must provide a role that has read access to these tables.

  • (dict) --

    Defines where the training dataset is located, what type of data it contains, and how to access the data.

    • inputConfig (dict) -- [REQUIRED]

      A DatasetInputConfig object that defines the data source and schema mapping.

      • dataSource (dict) -- [REQUIRED]

        A DataSource object that specifies the Glue data source for the training data.

        • glueDataSource (dict) -- [REQUIRED]

          A GlueDataSource object that defines the catalog ID, database name, and table name for the training data.

          • catalogId (string) --

            The Glue catalog that contains the training data.

          • databaseName (string) -- [REQUIRED]

            The Glue database that contains the training data.

          • tableName (string) -- [REQUIRED]

            The Glue table that contains the training data.

      • schema (list) -- [REQUIRED]

        The schema information for the training data.

        • (dict) --

          Metadata for a column.

          • columnName (string) -- [REQUIRED]

            The name of a column.

          • columnTypes (list) -- [REQUIRED]

            The data type of column.

            • (string) --

    • type (string) -- [REQUIRED]

      What type of information is found in the dataset.

rtype

dict

returns

Response Syntax

{
    'trainingDatasetArn': 'string'
}

Response Structure

  • (dict) --

    • trainingDatasetArn (string) --

      The Amazon Resource Name (ARN) of the training dataset resource.

StartAudienceExportJob (new) Link ¶

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

See also: AWS API Documentation

Request Syntax

client.start_audience_export_job(
    audienceGenerationJobArn='string',
    audienceSize={
        'type': 'ABSOLUTE'|'PERCENTAGE',
        'value': 123
    },
    description='string',
    name='string'
)
type audienceGenerationJobArn

string

param audienceGenerationJobArn

[REQUIRED]

The Amazon Resource Name (ARN) of the audience generation job that you want to export.

type audienceSize

dict

param audienceSize

[REQUIRED]

The size of the generated audience. Must match one of the sizes in the configured audience model.

  • type (string) -- [REQUIRED]

    Whether the audience size is defined in absolute terms or as a percentage. You can use the ABSOLUTE AudienceSize to configure out audience sizes using the count of identifiers in the output. You can use the Percentage AudienceSize to configure sizes in the range 1-100 percent.

  • value (integer) -- [REQUIRED]

    Specify an audience size value.

type description

string

param description

The description of the audience export job.

type name

string

param name

[REQUIRED]

The name of the audience export job.

returns

None

GetAudienceGenerationJob (new) Link ¶

Returns information about an audience generation job.

See also: AWS API Documentation

Request Syntax

client.get_audience_generation_job(
    audienceGenerationJobArn='string'
)
type audienceGenerationJobArn

string

param audienceGenerationJobArn

[REQUIRED]

The Amazon Resource Name (ARN) of the audience generation job that you are interested in.

rtype

dict

returns

Response Syntax

{
    'audienceGenerationJobArn': 'string',
    'collaborationId': 'string',
    'configuredAudienceModelArn': 'string',
    'createTime': datetime(2015, 1, 1),
    'description': 'string',
    'includeSeedInOutput': True|False,
    'metrics': {
        'relevanceMetrics': [
            {
                'audienceSize': {
                    'type': 'ABSOLUTE'|'PERCENTAGE',
                    'value': 123
                },
                'score': 123.0
            },
        ]
    },
    'name': 'string',
    'seedAudience': {
        'dataSource': {
            's3Uri': 'string'
        },
        'roleArn': 'string'
    },
    'startedBy': 'string',
    'status': 'CREATE_PENDING'|'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'ACTIVE'|'DELETE_PENDING'|'DELETE_IN_PROGRESS'|'DELETE_FAILED',
    'statusDetails': {
        'message': 'string',
        'statusCode': 'string'
    },
    'tags': {
        'string': 'string'
    },
    'updateTime': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • audienceGenerationJobArn (string) --

      The Amazon Resource Name (ARN) of the audience generation job.

    • collaborationId (string) --

      The identifier of the collaboration that this audience generation job is associated with.

    • configuredAudienceModelArn (string) --

      The Amazon Resource Name (ARN) of the configured audience model used for this audience generation job.

    • createTime (datetime) --

      The time at which the audience generation job was created.

    • description (string) --

      The description of the audience generation job.

    • includeSeedInOutput (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 (dict) --

      The relevance scores for different audience sizes.

      • relevanceMetrics (list) --

        The relevance scores of the generated audience.

        • (dict) --

          The relevance score of a generated audience.

          • audienceSize (dict) --

            The size of the generated audience. Must match one of the sizes in the configured audience model.

            • type (string) --

              Whether the audience size is defined in absolute terms or as a percentage. You can use the ABSOLUTE AudienceSize to configure out audience sizes using the count of identifiers in the output. You can use the Percentage AudienceSize to configure sizes in the range 1-100 percent.

            • value (integer) --

              Specify an audience size value.

          • score (float) --

            The relevance score of the generated audience.

    • name (string) --

      The name of the audience generation job.

    • seedAudience (dict) --

      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.

      • dataSource (dict) --

        The Amazon S3 bucket where the training data for the configured audience is stored.

        • s3Uri (string) --

          The Amazon S3 location URI.

      • roleArn (string) --

        The ARN of the IAM role that can read the Amazon S3 bucket where the training data is stored.

    • startedBy (string) --

      The AWS account that started this audience generation job.

    • status (string) --

      The status of the audience generation job.

    • statusDetails (dict) --

      Details about the status of the audience generation job.

      • message (string) --

        The error message that was returned. The message is intended for human consumption and can change at any time. Use the statusCode for programmatic error handling.

      • statusCode (string) --

        The status code that was returned. The status code is intended for programmatic error handling. Clean Rooms ML will not change the status code for existing error conditions.

    • tags (dict) --

      The tags that are associated to this audience generation job.

      • (string) --

        • (string) --

    • updateTime (datetime) --

      The most recent time at which the audience generation job was updated.