2022/11/17 - Amazon Personalize - 6 new 5 updated api methods
Changes This release provides support for creation and use of metric attributions in AWS Personalize
Lists metric attributions.
See also: AWS API Documentation
Request Syntax
client.list_metric_attributions(
datasetGroupArn='string',
nextToken='string',
maxResults=123
)
string
The metric attributions' dataset group Amazon Resource Name (ARN).
string
Specify the pagination token from a previous request to retrieve the next page of results.
integer
The maximum number of metric attributions to return in one page of results.
dict
Response Syntax
{
'metricAttributions': [
{
'name': 'string',
'metricAttributionArn': 'string',
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'failureReason': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
metricAttributions (list) --
The list of metric attributions.
(dict) --
Provides a summary of the properties of a metric attribution. For a complete listing, call the DescribeMetricAttribution .
name (string) --
The name of the metric attribution.
metricAttributionArn (string) --
The metric attribution's Amazon Resource Name (ARN).
status (string) --
The metric attribution's status.
creationDateTime (datetime) --
The metric attribution's creation date time.
lastUpdatedDateTime (datetime) --
The metric attribution's last updated date time.
failureReason (string) --
The metric attribution's failure reason.
nextToken (string) --
Specify the pagination token from a previous request to retrieve the next page of results.
Updates a metric attribution.
See also: AWS API Documentation
Request Syntax
client.update_metric_attribution(
addMetrics=[
{
'eventType': 'string',
'metricName': 'string',
'expression': 'string'
},
],
removeMetrics=[
'string',
],
metricsOutputConfig={
's3DataDestination': {
'path': 'string',
'kmsKeyArn': 'string'
},
'roleArn': 'string'
},
metricAttributionArn='string'
)
list
Add new metric attributes to the metric attribution.
(dict) --
Contains information on a metric that a metric attribution reports on. For more information, see Measuring impact of recommendations .
eventType (string) -- [REQUIRED]
The metric's event type.
metricName (string) -- [REQUIRED]
The metric's name. The name helps you identify the metric in Amazon CloudWatch or Amazon S3.
expression (string) -- [REQUIRED]
The attribute's expression. Available functions are SUM() or SAMPLECOUNT() . For SUM() functions, provide the dataset type (either Interactions or Items) and column to sum as a parameter. For example SUM(Items.PRICE).
list
Remove metric attributes from the metric attribution.
(string) --
dict
An output config for the metric attribution.
s3DataDestination (dict) --
The configuration details of an Amazon S3 input or output bucket.
path (string) -- [REQUIRED]
The file path of the Amazon S3 bucket.
kmsKeyArn (string) --
The Amazon Resource Name (ARN) of the Key Management Service (KMS) key that Amazon Personalize uses to encrypt or decrypt the input and output files.
roleArn (string) -- [REQUIRED]
The Amazon Resource Name (ARN) of the IAM service role that has permissions to add data to your output Amazon S3 bucket and add metrics to Amazon CloudWatch. For more information, see Measuring impact of recommendations .
string
The Amazon Resource Name (ARN) for the metric attribution to update.
dict
Response Syntax
{
'metricAttributionArn': 'string'
}
Response Structure
(dict) --
metricAttributionArn (string) --
The Amazon Resource Name (ARN) for the metric attribution that you updated.
Creates a metric attribution. A metric attribution creates reports on the data that you import into Amazon Personalize. Depending on how you imported the data, you can view reports in Amazon CloudWatch or Amazon S3. For more information, see Measuring impact of recommendations .
See also: AWS API Documentation
Request Syntax
client.create_metric_attribution(
name='string',
datasetGroupArn='string',
metrics=[
{
'eventType': 'string',
'metricName': 'string',
'expression': 'string'
},
],
metricsOutputConfig={
's3DataDestination': {
'path': 'string',
'kmsKeyArn': 'string'
},
'roleArn': 'string'
}
)
string
[REQUIRED]
A name for the metric attribution.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the destination dataset group for the metric attribution.
list
[REQUIRED]
A list of metric attributes for the metric attribution. Each metric attribute specifies an event type to track and a function. Available functions are SUM() or SAMPLECOUNT() . For SUM() functions, provide the dataset type (either Interactions or Items) and column to sum as a parameter. For example SUM(Items.PRICE).
(dict) --
Contains information on a metric that a metric attribution reports on. For more information, see Measuring impact of recommendations .
eventType (string) -- [REQUIRED]
The metric's event type.
metricName (string) -- [REQUIRED]
The metric's name. The name helps you identify the metric in Amazon CloudWatch or Amazon S3.
expression (string) -- [REQUIRED]
The attribute's expression. Available functions are SUM() or SAMPLECOUNT() . For SUM() functions, provide the dataset type (either Interactions or Items) and column to sum as a parameter. For example SUM(Items.PRICE).
dict
[REQUIRED]
The output configuration details for the metric attribution.
s3DataDestination (dict) --
The configuration details of an Amazon S3 input or output bucket.
path (string) -- [REQUIRED]
The file path of the Amazon S3 bucket.
kmsKeyArn (string) --
The Amazon Resource Name (ARN) of the Key Management Service (KMS) key that Amazon Personalize uses to encrypt or decrypt the input and output files.
roleArn (string) -- [REQUIRED]
The Amazon Resource Name (ARN) of the IAM service role that has permissions to add data to your output Amazon S3 bucket and add metrics to Amazon CloudWatch. For more information, see Measuring impact of recommendations .
dict
Response Syntax
{
'metricAttributionArn': 'string'
}
Response Structure
(dict) --
metricAttributionArn (string) --
The Amazon Resource Name (ARN) for the new metric attribution.
Lists the metrics for the metric attribution.
See also: AWS API Documentation
Request Syntax
client.list_metric_attribution_metrics(
metricAttributionArn='string',
nextToken='string',
maxResults=123
)
string
The Amazon Resource Name (ARN) of the metric attribution to retrieve attributes for.
string
Specify the pagination token from a previous request to retrieve the next page of results.
integer
The maximum number of metrics to return in one page of results.
dict
Response Syntax
{
'metrics': [
{
'eventType': 'string',
'metricName': 'string',
'expression': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
metrics (list) --
The metrics for the specified metric attribution.
(dict) --
Contains information on a metric that a metric attribution reports on. For more information, see Measuring impact of recommendations .
eventType (string) --
The metric's event type.
metricName (string) --
The metric's name. The name helps you identify the metric in Amazon CloudWatch or Amazon S3.
expression (string) --
The attribute's expression. Available functions are SUM() or SAMPLECOUNT() . For SUM() functions, provide the dataset type (either Interactions or Items) and column to sum as a parameter. For example SUM(Items.PRICE).
nextToken (string) --
Specify the pagination token from a previous ListMetricAttributionMetricsResponse request to retrieve the next page of results.
Deletes a metric attribution.
See also: AWS API Documentation
Request Syntax
client.delete_metric_attribution(
metricAttributionArn='string'
)
string
[REQUIRED]
The metric attribution's Amazon Resource Name (ARN).
None
Describes a metric attribution.
See also: AWS API Documentation
Request Syntax
client.describe_metric_attribution(
metricAttributionArn='string'
)
string
[REQUIRED]
The metric attribution's Amazon Resource Name (ARN).
dict
Response Syntax
{
'metricAttribution': {
'name': 'string',
'metricAttributionArn': 'string',
'datasetGroupArn': 'string',
'metricsOutputConfig': {
's3DataDestination': {
'path': 'string',
'kmsKeyArn': 'string'
},
'roleArn': 'string'
},
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'failureReason': 'string'
}
}
Response Structure
(dict) --
metricAttribution (dict) --
The details of the metric attribution.
name (string) --
The metric attribution's name.
metricAttributionArn (string) --
The metric attribution's Amazon Resource Name (ARN).
datasetGroupArn (string) --
The metric attribution's dataset group Amazon Resource Name (ARN).
metricsOutputConfig (dict) --
The metric attribution's output configuration.
s3DataDestination (dict) --
The configuration details of an Amazon S3 input or output bucket.
path (string) --
The file path of the Amazon S3 bucket.
kmsKeyArn (string) --
The Amazon Resource Name (ARN) of the Key Management Service (KMS) key that Amazon Personalize uses to encrypt or decrypt the input and output files.
roleArn (string) --
The Amazon Resource Name (ARN) of the IAM service role that has permissions to add data to your output Amazon S3 bucket and add metrics to Amazon CloudWatch. For more information, see Measuring impact of recommendations .
status (string) --
The metric attribution's status.
creationDateTime (datetime) --
The metric attribution's creation date time.
lastUpdatedDateTime (datetime) --
The metric attribution's last updated date time.
failureReason (string) --
The metric attribution's failure reason.
{'publishAttributionMetricsToS3': 'boolean'}
Creates a job that imports training data from your data source (an Amazon S3 bucket) to an Amazon Personalize dataset. To allow Amazon Personalize to import the training data, you must specify an IAM service role that has permission to read from the data source, as Amazon Personalize makes a copy of your data and processes it internally. For information on granting access to your Amazon S3 bucket, see Giving Amazon Personalize Access to Amazon S3 Resources .
Warning
By default, a dataset import job replaces any existing data in the dataset that you imported in bulk. To add new records without replacing existing data, specify INCREMENTAL for the import mode in the CreateDatasetImportJob operation.
Status
A dataset import job can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
To get the status of the import job, call DescribeDatasetImportJob , providing the Amazon Resource Name (ARN) of the dataset import job. The dataset import is complete when the status shows as ACTIVE. If the status shows as CREATE FAILED, the response includes a failureReason key, which describes why the job failed.
Note
Importing takes time. You must wait until the status shows as ACTIVE before training a model using the dataset.
Related APIs
See also: AWS API Documentation
Request Syntax
client.create_dataset_import_job(
jobName='string',
datasetArn='string',
dataSource={
'dataLocation': 'string'
},
roleArn='string',
tags=[
{
'tagKey': 'string',
'tagValue': 'string'
},
],
importMode='FULL'|'INCREMENTAL',
publishAttributionMetricsToS3=True|False
)
string
[REQUIRED]
The name for the dataset import job.
string
[REQUIRED]
The ARN of the dataset that receives the imported data.
dict
[REQUIRED]
The Amazon S3 bucket that contains the training data to import.
dataLocation (string) --
The path to the Amazon S3 bucket where the data that you want to upload to your dataset is stored. For example:
s3://bucket-name/folder-name/
string
[REQUIRED]
The ARN of the IAM role that has permissions to read from the Amazon S3 data source.
list
A list of tags to apply to the dataset import job.
(dict) --
The optional metadata that you apply to resources to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. For more information see Tagging Personalize resources .
tagKey (string) -- [REQUIRED]
One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.
tagValue (string) -- [REQUIRED]
The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).
string
Specify how to add the new records to an existing dataset. The default import mode is FULL . If you haven't imported bulk records into the dataset previously, you can only specify FULL .
Specify FULL to overwrite all existing bulk data in your dataset. Data you imported individually is not replaced.
Specify INCREMENTAL to append the new records to the existing data in your dataset. Amazon Personalize replaces any record with the same ID with the new one.
boolean
If you created a metric attribution, specify whether to publish metrics for this import job to Amazon S3
dict
Response Syntax
{
'datasetImportJobArn': 'string'
}
Response Structure
(dict) --
datasetImportJobArn (string) --
The ARN of the dataset import job.
{'name': 'string'}
Trains or retrains an active solution in a Custom dataset group. A solution is created using the CreateSolution operation and must be in the ACTIVE state before calling CreateSolutionVersion . A new version of the solution is created every time you call this operation.
Status
A solution version can be in one of the following states:
CREATE PENDING
CREATE IN_PROGRESS
ACTIVE
CREATE FAILED
CREATE STOPPING
CREATE STOPPED
To get the status of the version, call DescribeSolutionVersion . Wait until the status shows as ACTIVE before calling CreateCampaign .
If the status shows as CREATE FAILED, the response includes a failureReason key, which describes why the job failed.
Related APIs
See also: AWS API Documentation
Request Syntax
client.create_solution_version(
name='string',
solutionArn='string',
trainingMode='FULL'|'UPDATE',
tags=[
{
'tagKey': 'string',
'tagValue': 'string'
},
]
)
string
The name of the solution version.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the solution containing the training configuration information.
string
The scope of training to be performed when creating the solution version. The FULL option trains the solution version based on the entirety of the input solution's training data, while the UPDATE option processes only the data that has changed in comparison to the input solution. Choose UPDATE when you want to incrementally update your solution version instead of creating an entirely new one.
Warning
The UPDATE option can only be used when you already have an active solution version created from the input solution using the FULL option and the input solution was trained with the User-Personalization recipe or the HRNN-Coldstart recipe.
list
A list of tags to apply to the solution version.
(dict) --
The optional metadata that you apply to resources to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. For more information see Tagging Personalize resources .
tagKey (string) -- [REQUIRED]
One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.
tagValue (string) -- [REQUIRED]
The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).
dict
Response Syntax
{
'solutionVersionArn': 'string'
}
Response Structure
(dict) --
solutionVersionArn (string) --
The ARN of the new solution version.
{'datasetImportJob': {'publishAttributionMetricsToS3': 'boolean'}}
Describes the dataset import job created by CreateDatasetImportJob , including the import job status.
See also: AWS API Documentation
Request Syntax
client.describe_dataset_import_job(
datasetImportJobArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the dataset import job to describe.
dict
Response Syntax
{
'datasetImportJob': {
'jobName': 'string',
'datasetImportJobArn': 'string',
'datasetArn': 'string',
'dataSource': {
'dataLocation': 'string'
},
'roleArn': 'string',
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'failureReason': 'string',
'importMode': 'FULL'|'INCREMENTAL',
'publishAttributionMetricsToS3': True|False
}
}
Response Structure
(dict) --
datasetImportJob (dict) --
Information about the dataset import job, including the status.
The status is one of the following values:
CREATE PENDING
CREATE IN_PROGRESS
ACTIVE
CREATE FAILED
jobName (string) --
The name of the import job.
datasetImportJobArn (string) --
The ARN of the dataset import job.
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset that receives the imported data.
dataSource (dict) --
The Amazon S3 bucket that contains the training data to import.
dataLocation (string) --
The path to the Amazon S3 bucket where the data that you want to upload to your dataset is stored. For example:
s3://bucket-name/folder-name/
roleArn (string) --
The ARN of the IAM role that has permissions to read from the Amazon S3 data source.
status (string) --
The status of the dataset import job.
A dataset import job can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
creationDateTime (datetime) --
The creation date and time (in Unix time) of the dataset import job.
lastUpdatedDateTime (datetime) --
The date and time (in Unix time) the dataset was last updated.
failureReason (string) --
If a dataset import job fails, provides the reason why.
importMode (string) --
The import mode used by the dataset import job to import new records.
publishAttributionMetricsToS3 (boolean) --
Whether the job publishes metrics to Amazon S3 for a metric attribution.
{'solutionVersion': {'name': 'string'}}
Describes a specific version of a solution. For more information on solutions, see CreateSolution
See also: AWS API Documentation
Request Syntax
client.describe_solution_version(
solutionVersionArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the solution version.
dict
Response Syntax
{
'solutionVersion': {
'name': 'string',
'solutionVersionArn': 'string',
'solutionArn': 'string',
'performHPO': True|False,
'performAutoML': True|False,
'recipeArn': 'string',
'eventType': 'string',
'datasetGroupArn': 'string',
'solutionConfig': {
'eventValueThreshold': 'string',
'hpoConfig': {
'hpoObjective': {
'type': 'string',
'metricName': 'string',
'metricRegex': 'string'
},
'hpoResourceConfig': {
'maxNumberOfTrainingJobs': 'string',
'maxParallelTrainingJobs': 'string'
},
'algorithmHyperParameterRanges': {
'integerHyperParameterRanges': [
{
'name': 'string',
'minValue': 123,
'maxValue': 123
},
],
'continuousHyperParameterRanges': [
{
'name': 'string',
'minValue': 123.0,
'maxValue': 123.0
},
],
'categoricalHyperParameterRanges': [
{
'name': 'string',
'values': [
'string',
]
},
]
}
},
'algorithmHyperParameters': {
'string': 'string'
},
'featureTransformationParameters': {
'string': 'string'
},
'autoMLConfig': {
'metricName': 'string',
'recipeList': [
'string',
]
},
'optimizationObjective': {
'itemAttribute': 'string',
'objectiveSensitivity': 'LOW'|'MEDIUM'|'HIGH'|'OFF'
}
},
'trainingHours': 123.0,
'trainingMode': 'FULL'|'UPDATE',
'tunedHPOParams': {
'algorithmHyperParameters': {
'string': 'string'
}
},
'status': 'string',
'failureReason': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
solutionVersion (dict) --
The solution version.
name (string) --
The name of the solution version.
solutionVersionArn (string) --
The ARN of the solution version.
solutionArn (string) --
The ARN of the solution.
performHPO (boolean) --
Whether to perform hyperparameter optimization (HPO) on the chosen recipe. The default is false .
performAutoML (boolean) --
When true, Amazon Personalize searches for the most optimal recipe according to the solution configuration. When false (the default), Amazon Personalize uses recipeArn .
recipeArn (string) --
The ARN of the recipe used in the solution.
eventType (string) --
The event type (for example, 'click' or 'like') that is used for training the model.
datasetGroupArn (string) --
The Amazon Resource Name (ARN) of the dataset group providing the training data.
solutionConfig (dict) --
Describes the configuration properties for the solution.
eventValueThreshold (string) --
Only events with a value greater than or equal to this threshold are used for training a model.
hpoConfig (dict) --
Describes the properties for hyperparameter optimization (HPO).
hpoObjective (dict) --
The metric to optimize during HPO.
Note
Amazon Personalize doesn't support configuring the hpoObjective at this time.
type (string) --
The type of the metric. Valid values are Maximize and Minimize .
metricName (string) --
The name of the metric.
metricRegex (string) --
A regular expression for finding the metric in the training job logs.
hpoResourceConfig (dict) --
Describes the resource configuration for HPO.
maxNumberOfTrainingJobs (string) --
The maximum number of training jobs when you create a solution version. The maximum value for maxNumberOfTrainingJobs is 40 .
maxParallelTrainingJobs (string) --
The maximum number of parallel training jobs when you create a solution version. The maximum value for maxParallelTrainingJobs is 10 .
algorithmHyperParameterRanges (dict) --
The hyperparameters and their allowable ranges.
integerHyperParameterRanges (list) --
The integer-valued hyperparameters and their ranges.
(dict) --
Provides the name and range of an integer-valued hyperparameter.
name (string) --
The name of the hyperparameter.
minValue (integer) --
The minimum allowable value for the hyperparameter.
maxValue (integer) --
The maximum allowable value for the hyperparameter.
continuousHyperParameterRanges (list) --
The continuous hyperparameters and their ranges.
(dict) --
Provides the name and range of a continuous hyperparameter.
name (string) --
The name of the hyperparameter.
minValue (float) --
The minimum allowable value for the hyperparameter.
maxValue (float) --
The maximum allowable value for the hyperparameter.
categoricalHyperParameterRanges (list) --
The categorical hyperparameters and their ranges.
(dict) --
Provides the name and range of a categorical hyperparameter.
name (string) --
The name of the hyperparameter.
values (list) --
A list of the categories for the hyperparameter.
(string) --
algorithmHyperParameters (dict) --
Lists the hyperparameter names and ranges.
(string) --
(string) --
featureTransformationParameters (dict) --
Lists the feature transformation parameters.
(string) --
(string) --
autoMLConfig (dict) --
The AutoMLConfig object containing a list of recipes to search when AutoML is performed.
metricName (string) --
The metric to optimize.
recipeList (list) --
The list of candidate recipes.
(string) --
optimizationObjective (dict) --
Describes the additional objective for the solution, such as maximizing streaming minutes or increasing revenue. For more information see Optimizing a solution .
itemAttribute (string) --
The numerical metadata column in an Items dataset related to the optimization objective. For example, VIDEO_LENGTH (to maximize streaming minutes), or PRICE (to maximize revenue).
objectiveSensitivity (string) --
Specifies how Amazon Personalize balances the importance of your optimization objective versus relevance.
trainingHours (float) --
The time used to train the model. You are billed for the time it takes to train a model. This field is visible only after Amazon Personalize successfully trains a model.
trainingMode (string) --
The scope of training to be performed when creating the solution version. The FULL option trains the solution version based on the entirety of the input solution's training data, while the UPDATE option processes only the data that has changed in comparison to the input solution. Choose UPDATE when you want to incrementally update your solution version instead of creating an entirely new one.
Warning
The UPDATE option can only be used when you already have an active solution version created from the input solution using the FULL option and the input solution was trained with the User-Personalization recipe or the HRNN-Coldstart recipe.
tunedHPOParams (dict) --
If hyperparameter optimization was performed, contains the hyperparameter values of the best performing model.
algorithmHyperParameters (dict) --
A list of the hyperparameter values of the best performing model.
(string) --
(string) --
status (string) --
The status of the solution version.
A solution version can be in one of the following states:
CREATE PENDING
CREATE IN_PROGRESS
ACTIVE
CREATE FAILED
CREATE STOPPING
CREATE STOPPED
failureReason (string) --
If training a solution version fails, the reason for the failure.
creationDateTime (datetime) --
The date and time (in Unix time) that this version of the solution was created.
lastUpdatedDateTime (datetime) --
The date and time (in Unix time) that the solution was last updated.
{'solutions': {'recipeArn': 'string'}}
Returns a list of solutions that use the given dataset group. When a dataset group is not specified, all the solutions associated with the account are listed. The response provides the properties for each solution, including the Amazon Resource Name (ARN). For more information on solutions, see CreateSolution .
See also: AWS API Documentation
Request Syntax
client.list_solutions(
datasetGroupArn='string',
nextToken='string',
maxResults=123
)
string
The Amazon Resource Name (ARN) of the dataset group.
string
A token returned from the previous call to ListSolutions for getting the next set of solutions (if they exist).
integer
The maximum number of solutions to return.
dict
Response Syntax
{
'solutions': [
{
'name': 'string',
'solutionArn': 'string',
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'recipeArn': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
solutions (list) --
A list of the current solutions.
(dict) --
Provides a summary of the properties of a solution. For a complete listing, call the DescribeSolution API.
name (string) --
The name of the solution.
solutionArn (string) --
The Amazon Resource Name (ARN) of the solution.
status (string) --
The status of the solution.
A solution can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
DELETE PENDING > DELETE IN_PROGRESS
creationDateTime (datetime) --
The date and time (in Unix time) that the solution was created.
lastUpdatedDateTime (datetime) --
The date and time (in Unix time) that the solution was last updated.
recipeArn (string) --
The Amazon Resource Name (ARN) of the recipe used by the solution.
nextToken (string) --
A token for getting the next set of solutions (if they exist).