2023/11/27 - Amazon Personalize - 11 updated api methods
Changes Enables metadata in recommendations, recommendations with themes, and next best action recommendations
{'batchInferenceJobMode': 'BATCH_INFERENCE | THEME_GENERATION',
'themeGenerationConfig': {'fieldsForThemeGeneration': {'itemName': 'string'}}}
Generates batch recommendations based on a list of items or users stored in Amazon S3 and exports the recommendations to an Amazon S3 bucket.
To generate batch recommendations, specify the ARN of a solution version and an Amazon S3 URI for the input and output data. For user personalization, popular items, and personalized ranking solutions, the batch inference job generates a list of recommended items for each user ID in the input file. For related items solutions, the job generates a list of recommended items for each item ID in the input file.
For more information, see Creating a batch inference job.
If you use the Similar-Items recipe, Amazon Personalize can add descriptive themes to batch recommendations. To generate themes, set the job's mode to THEME_GENERATION and specify the name of the field that contains item names in the input data.
For more information about generating themes, see Batch recommendations with themes from Content Generator.
You can't get batch recommendations with the Trending-Now or Next-Best-Action recipes.
See also: AWS API Documentation
Request Syntax
client.create_batch_inference_job(
jobName='string',
solutionVersionArn='string',
filterArn='string',
numResults=123,
jobInput={
's3DataSource': {
'path': 'string',
'kmsKeyArn': 'string'
}
},
jobOutput={
's3DataDestination': {
'path': 'string',
'kmsKeyArn': 'string'
}
},
roleArn='string',
batchInferenceJobConfig={
'itemExplorationConfig': {
'string': 'string'
}
},
tags=[
{
'tagKey': 'string',
'tagValue': 'string'
},
],
batchInferenceJobMode='BATCH_INFERENCE'|'THEME_GENERATION',
themeGenerationConfig={
'fieldsForThemeGeneration': {
'itemName': 'string'
}
}
)
string
[REQUIRED]
The name of the batch inference job to create.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the solution version that will be used to generate the batch inference recommendations.
string
The ARN of the filter to apply to the batch inference job. For more information on using filters, see Filtering batch recommendations.
integer
The number of recommendations to retrieve.
dict
[REQUIRED]
The Amazon S3 path that leads to the input file to base your recommendations on. The input material must be in JSON format.
s3DataSource (dict) -- [REQUIRED]
The URI of the Amazon S3 location that contains your input data. The Amazon S3 bucket must be in the same region as the API endpoint you are calling.
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.
dict
[REQUIRED]
The path to the Amazon S3 bucket where the job's output will be stored.
s3DataDestination (dict) -- [REQUIRED]
Information on the Amazon S3 bucket in which the batch inference job's output is stored.
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.
string
[REQUIRED]
The ARN of the Amazon Identity and Access Management role that has permissions to read and write to your input and output Amazon S3 buckets respectively.
dict
The configuration details of a batch inference job.
itemExplorationConfig (dict) --
A string to string map specifying the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. See User-Personalization.
(string) --
(string) --
list
A list of tags to apply to the batch inference 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 Amazon Personalize recources.
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
The mode of the batch inference job. To generate descriptive themes for groups of similar items, set the job mode to THEME_GENERATION . If you don't want to generate themes, use the default BATCH_INFERENCE .
When you get batch recommendations with themes, you will incur additional costs. For more information, see Amazon Personalize pricing.
dict
For theme generation jobs, specify the name of the column in your Items dataset that contains each item's name.
fieldsForThemeGeneration (dict) -- [REQUIRED]
Fields used to generate descriptive themes for a batch inference job.
itemName (string) -- [REQUIRED]
The name of the Items dataset column that stores the name of each item in the dataset.
dict
Response Syntax
{
'batchInferenceJobArn': 'string'
}
Response Structure
(dict) --
batchInferenceJobArn (string) --
The ARN of the batch inference job.
{'campaignConfig': {'enableMetadataWithRecommendations': 'boolean'}}
Creates a campaign that deploys a solution version. When a client calls the GetRecommendations and GetPersonalizedRanking APIs, a campaign is specified in the request.
Minimum Provisioned TPS and Auto-Scaling
Warning
A high minProvisionedTPS will increase your bill. We recommend starting with 1 for minProvisionedTPS (the default). Track your usage using Amazon CloudWatch metrics, and increase the minProvisionedTPS as necessary.
A transaction is a single GetRecommendations or GetPersonalizedRanking call. Transactions per second (TPS) is the throughput and unit of billing for Amazon Personalize. The minimum provisioned TPS ( minProvisionedTPS ) specifies the baseline throughput provisioned by Amazon Personalize, and thus, the minimum billing charge.
If your TPS increases beyond minProvisionedTPS , Amazon Personalize auto-scales the provisioned capacity up and down, but never below minProvisionedTPS . There's a short time delay while the capacity is increased that might cause loss of transactions.
The actual TPS used is calculated as the average requests/second within a 5-minute window. You pay for maximum of either the minimum provisioned TPS or the actual TPS. We recommend starting with a low minProvisionedTPS , track your usage using Amazon CloudWatch metrics, and then increase the minProvisionedTPS as necessary.
Status
A campaign can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
DELETE PENDING > DELETE IN_PROGRESS
To get the campaign status, call DescribeCampaign.
Note
Wait until the status of the campaign is ACTIVE before asking the campaign for recommendations.
Related APIs
See also: AWS API Documentation
Request Syntax
client.create_campaign(
name='string',
solutionVersionArn='string',
minProvisionedTPS=123,
campaignConfig={
'itemExplorationConfig': {
'string': 'string'
},
'enableMetadataWithRecommendations': True|False
},
tags=[
{
'tagKey': 'string',
'tagValue': 'string'
},
]
)
string
[REQUIRED]
A name for the new campaign. The campaign name must be unique within your account.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the solution version to deploy.
integer
Specifies the requested minimum provisioned transactions (recommendations) per second that Amazon Personalize will support. A high minProvisionedTPS will increase your bill. We recommend starting with 1 for minProvisionedTPS (the default). Track your usage using Amazon CloudWatch metrics, and increase the minProvisionedTPS as necessary.
dict
The configuration details of a campaign.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your solution uses the User-Personalization recipe.
(string) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the campaign. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
list
A list of tags to apply to the campaign.
(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 Amazon Personalize recources.
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
{
'campaignArn': 'string'
}
Response Structure
(dict) --
campaignArn (string) --
The Amazon Resource Name (ARN) of the campaign.
{'recommenderConfig': {'enableMetadataWithRecommendations': 'boolean'}}
Creates a recommender with the recipe (a Domain dataset group use case) you specify. You create recommenders for a Domain dataset group and specify the recommender's Amazon Resource Name (ARN) when you make a GetRecommendations request.
Minimum recommendation requests per second
Warning
A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.
When you create a recommender, you can configure the recommender's minimum recommendation requests per second. The minimum recommendation requests per second ( minRecommendationRequestsPerSecond ) specifies the baseline recommendation request throughput provisioned by Amazon Personalize. The default minRecommendationRequestsPerSecond is 1 . A recommendation request is a single GetRecommendations operation. Request throughput is measured in requests per second and Amazon Personalize uses your requests per second to derive your requests per hour and the price of your recommender usage.
If your requests per second increases beyond minRecommendationRequestsPerSecond , Amazon Personalize auto-scales the provisioned capacity up and down, but never below minRecommendationRequestsPerSecond . There's a short time delay while the capacity is increased that might cause loss of requests.
Your bill is the greater of either the minimum requests per hour (based on minRecommendationRequestsPerSecond) or the actual number of requests. The actual request throughput used is calculated as the average requests/second within a one-hour window. We recommend starting with the default minRecommendationRequestsPerSecond , track your usage using Amazon CloudWatch metrics, and then increase the minRecommendationRequestsPerSecond as necessary.
Status
A recommender can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE
DELETE PENDING > DELETE IN_PROGRESS
To get the recommender status, call DescribeRecommender.
Note
Wait until the status of the recommender is ACTIVE before asking the recommender for recommendations.
Related APIs
See also: AWS API Documentation
Request Syntax
client.create_recommender(
name='string',
datasetGroupArn='string',
recipeArn='string',
recommenderConfig={
'itemExplorationConfig': {
'string': 'string'
},
'minRecommendationRequestsPerSecond': 123,
'trainingDataConfig': {
'excludedDatasetColumns': {
'string': [
'string',
]
}
},
'enableMetadataWithRecommendations': True|False
},
tags=[
{
'tagKey': 'string',
'tagValue': 'string'
},
]
)
string
[REQUIRED]
The name of the recommender.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the destination domain dataset group for the recommender.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the recipe that the recommender will use. For a recommender, a recipe is a Domain dataset group use case. Only Domain dataset group use cases can be used to create a recommender. For information about use cases see Choosing recommender use cases.
dict
The configuration details of the recommender.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).
(string) --
(string) --
minRecommendationRequestsPerSecond (integer) --
Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.
trainingDataConfig (dict) --
Specifies the training data configuration to use when creating a domain recommender.
excludedDatasetColumns (dict) --
Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.
(string) --
(list) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the recommender. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
list
A list of tags to apply to the recommender.
(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 Amazon Personalize recources.
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
{
'recommenderArn': 'string'
}
Response Structure
(dict) --
recommenderArn (string) --
The Amazon Resource Name (ARN) of the recommender.
{'batchInferenceJob': {'batchInferenceJobMode': 'BATCH_INFERENCE | '
'THEME_GENERATION',
'themeGenerationConfig': {'fieldsForThemeGeneration': {'itemName': 'string'}}}}
Gets the properties of a batch inference job including name, Amazon Resource Name (ARN), status, input and output configurations, and the ARN of the solution version used to generate the recommendations.
See also: AWS API Documentation
Request Syntax
client.describe_batch_inference_job(
batchInferenceJobArn='string'
)
string
[REQUIRED]
The ARN of the batch inference job to describe.
dict
Response Syntax
{
'batchInferenceJob': {
'jobName': 'string',
'batchInferenceJobArn': 'string',
'filterArn': 'string',
'failureReason': 'string',
'solutionVersionArn': 'string',
'numResults': 123,
'jobInput': {
's3DataSource': {
'path': 'string',
'kmsKeyArn': 'string'
}
},
'jobOutput': {
's3DataDestination': {
'path': 'string',
'kmsKeyArn': 'string'
}
},
'batchInferenceJobConfig': {
'itemExplorationConfig': {
'string': 'string'
}
},
'roleArn': 'string',
'batchInferenceJobMode': 'BATCH_INFERENCE'|'THEME_GENERATION',
'themeGenerationConfig': {
'fieldsForThemeGeneration': {
'itemName': 'string'
}
},
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
batchInferenceJob (dict) --
Information on the specified batch inference job.
jobName (string) --
The name of the batch inference job.
batchInferenceJobArn (string) --
The Amazon Resource Name (ARN) of the batch inference job.
filterArn (string) --
The ARN of the filter used on the batch inference job.
failureReason (string) --
If the batch inference job failed, the reason for the failure.
solutionVersionArn (string) --
The Amazon Resource Name (ARN) of the solution version from which the batch inference job was created.
numResults (integer) --
The number of recommendations generated by the batch inference job. This number includes the error messages generated for failed input records.
jobInput (dict) --
The Amazon S3 path that leads to the input data used to generate the batch inference job.
s3DataSource (dict) --
The URI of the Amazon S3 location that contains your input data. The Amazon S3 bucket must be in the same region as the API endpoint you are calling.
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.
jobOutput (dict) --
The Amazon S3 bucket that contains the output data generated by the batch inference job.
s3DataDestination (dict) --
Information on the Amazon S3 bucket in which the batch inference job's output is stored.
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.
batchInferenceJobConfig (dict) --
A string to string map of the configuration details of a batch inference job.
itemExplorationConfig (dict) --
A string to string map specifying the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. See User-Personalization.
(string) --
(string) --
roleArn (string) --
The ARN of the Amazon Identity and Access Management (IAM) role that requested the batch inference job.
batchInferenceJobMode (string) --
The job's mode.
themeGenerationConfig (dict) --
The job's theme generation settings.
fieldsForThemeGeneration (dict) --
Fields used to generate descriptive themes for a batch inference job.
itemName (string) --
The name of the Items dataset column that stores the name of each item in the dataset.
status (string) --
The status of the batch inference job. The status is one of the following values:
PENDING
IN PROGRESS
ACTIVE
CREATE FAILED
creationDateTime (datetime) --
The time at which the batch inference job was created.
lastUpdatedDateTime (datetime) --
The time at which the batch inference job was last updated.
{'campaign': {'campaignConfig': {'enableMetadataWithRecommendations': 'boolean'},
'latestCampaignUpdate': {'campaignConfig': {'enableMetadataWithRecommendations': 'boolean'}}}}
Describes the given campaign, including its status.
A campaign can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
DELETE PENDING > DELETE IN_PROGRESS
When the status is CREATE FAILED , the response includes the failureReason key, which describes why.
For more information on campaigns, see CreateCampaign.
See also: AWS API Documentation
Request Syntax
client.describe_campaign(
campaignArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the campaign.
dict
Response Syntax
{
'campaign': {
'name': 'string',
'campaignArn': 'string',
'solutionVersionArn': 'string',
'minProvisionedTPS': 123,
'campaignConfig': {
'itemExplorationConfig': {
'string': 'string'
},
'enableMetadataWithRecommendations': True|False
},
'status': 'string',
'failureReason': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'latestCampaignUpdate': {
'solutionVersionArn': 'string',
'minProvisionedTPS': 123,
'campaignConfig': {
'itemExplorationConfig': {
'string': 'string'
},
'enableMetadataWithRecommendations': True|False
},
'status': 'string',
'failureReason': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1)
}
}
}
Response Structure
(dict) --
campaign (dict) --
The properties of the campaign.
name (string) --
The name of the campaign.
campaignArn (string) --
The Amazon Resource Name (ARN) of the campaign.
solutionVersionArn (string) --
The Amazon Resource Name (ARN) of a specific version of the solution.
minProvisionedTPS (integer) --
Specifies the requested minimum provisioned transactions (recommendations) per second. A high minProvisionedTPS will increase your bill. We recommend starting with 1 for minProvisionedTPS (the default). Track your usage using Amazon CloudWatch metrics, and increase the minProvisionedTPS as necessary.
campaignConfig (dict) --
The configuration details of a campaign.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your solution uses the User-Personalization recipe.
(string) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the campaign. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
status (string) --
The status of the campaign.
A campaign can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
DELETE PENDING > DELETE IN_PROGRESS
failureReason (string) --
If a campaign fails, the reason behind the failure.
creationDateTime (datetime) --
The date and time (in Unix format) that the campaign was created.
lastUpdatedDateTime (datetime) --
The date and time (in Unix format) that the campaign was last updated.
latestCampaignUpdate (dict) --
Provides a summary of the properties of a campaign update. For a complete listing, call the DescribeCampaign API.
solutionVersionArn (string) --
The Amazon Resource Name (ARN) of the deployed solution version.
minProvisionedTPS (integer) --
Specifies the requested minimum provisioned transactions (recommendations) per second that Amazon Personalize will support.
campaignConfig (dict) --
The configuration details of a campaign.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your solution uses the User-Personalization recipe.
(string) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the campaign. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
status (string) --
The status of the campaign update.
A campaign update can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
DELETE PENDING > DELETE IN_PROGRESS
failureReason (string) --
If a campaign update fails, the reason behind the failure.
creationDateTime (datetime) --
The date and time (in Unix time) that the campaign update was created.
lastUpdatedDateTime (datetime) --
The date and time (in Unix time) that the campaign update was last updated.
{'dataset': {'trackingId': 'string'}}
Describes the given dataset. For more information on datasets, see CreateDataset.
See also: AWS API Documentation
Request Syntax
client.describe_dataset(
datasetArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the dataset to describe.
dict
Response Syntax
{
'dataset': {
'name': 'string',
'datasetArn': 'string',
'datasetGroupArn': 'string',
'datasetType': 'string',
'schemaArn': 'string',
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'latestDatasetUpdate': {
'schemaArn': 'string',
'status': 'string',
'failureReason': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1)
},
'trackingId': 'string'
}
}
Response Structure
(dict) --
dataset (dict) --
A listing of the dataset's properties.
name (string) --
The name of the dataset.
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset that you want metadata for.
datasetGroupArn (string) --
The Amazon Resource Name (ARN) of the dataset group.
datasetType (string) --
One of the following values:
Interactions
Items
Users
Actions
Action_Interactions
schemaArn (string) --
The ARN of the associated schema.
status (string) --
The status of the dataset.
A dataset 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 creation date and time (in Unix time) of the dataset.
lastUpdatedDateTime (datetime) --
A time stamp that shows when the dataset was updated.
latestDatasetUpdate (dict) --
Describes the latest update to the dataset.
schemaArn (string) --
The Amazon Resource Name (ARN) of the schema that replaced the previous schema of the dataset.
status (string) --
The status of the dataset update.
failureReason (string) --
If updating a dataset fails, provides the reason why.
creationDateTime (datetime) --
The creation date and time (in Unix time) of the dataset update.
lastUpdatedDateTime (datetime) --
The last update date and time (in Unix time) of the dataset.
trackingId (string) --
The ID of the event tracker for an Action interactions dataset. You specify the tracker's ID in the PutActionInteractions API operation. Amazon Personalize uses it to direct new data to the Action interactions dataset in your dataset group.
{'recommender': {'latestRecommenderUpdate': {'recommenderConfig': {'enableMetadataWithRecommendations': 'boolean'}},
'recommenderConfig': {'enableMetadataWithRecommendations': 'boolean'}}}
Describes the given recommender, including its status.
A recommender can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE
DELETE PENDING > DELETE IN_PROGRESS
When the status is CREATE FAILED , the response includes the failureReason key, which describes why.
The modelMetrics key is null when the recommender is being created or deleted.
For more information on recommenders, see CreateRecommender.
See also: AWS API Documentation
Request Syntax
client.describe_recommender(
recommenderArn='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the recommender to describe.
dict
Response Syntax
{
'recommender': {
'recommenderArn': 'string',
'datasetGroupArn': 'string',
'name': 'string',
'recipeArn': 'string',
'recommenderConfig': {
'itemExplorationConfig': {
'string': 'string'
},
'minRecommendationRequestsPerSecond': 123,
'trainingDataConfig': {
'excludedDatasetColumns': {
'string': [
'string',
]
}
},
'enableMetadataWithRecommendations': True|False
},
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'status': 'string',
'failureReason': 'string',
'latestRecommenderUpdate': {
'recommenderConfig': {
'itemExplorationConfig': {
'string': 'string'
},
'minRecommendationRequestsPerSecond': 123,
'trainingDataConfig': {
'excludedDatasetColumns': {
'string': [
'string',
]
}
},
'enableMetadataWithRecommendations': True|False
},
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'status': 'string',
'failureReason': 'string'
},
'modelMetrics': {
'string': 123.0
}
}
}
Response Structure
(dict) --
recommender (dict) --
The properties of the recommender.
recommenderArn (string) --
The Amazon Resource Name (ARN) of the recommender.
datasetGroupArn (string) --
The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender.
name (string) --
The name of the recommender.
recipeArn (string) --
The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for.
recommenderConfig (dict) --
The configuration details of the recommender.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).
(string) --
(string) --
minRecommendationRequestsPerSecond (integer) --
Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.
trainingDataConfig (dict) --
Specifies the training data configuration to use when creating a domain recommender.
excludedDatasetColumns (dict) --
Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.
(string) --
(list) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the recommender. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
creationDateTime (datetime) --
The date and time (in Unix format) that the recommender was created.
lastUpdatedDateTime (datetime) --
The date and time (in Unix format) that the recommender was last updated.
status (string) --
The status of the recommender.
A recommender can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE
DELETE PENDING > DELETE IN_PROGRESS
failureReason (string) --
If a recommender fails, the reason behind the failure.
latestRecommenderUpdate (dict) --
Provides a summary of the latest updates to the recommender.
recommenderConfig (dict) --
The configuration details of the recommender update.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).
(string) --
(string) --
minRecommendationRequestsPerSecond (integer) --
Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.
trainingDataConfig (dict) --
Specifies the training data configuration to use when creating a domain recommender.
excludedDatasetColumns (dict) --
Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.
(string) --
(list) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the recommender. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
creationDateTime (datetime) --
The date and time (in Unix format) that the recommender update was created.
lastUpdatedDateTime (datetime) --
The date and time (in Unix time) that the recommender update was last updated.
status (string) --
The status of the recommender update.
A recommender can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE
DELETE PENDING > DELETE IN_PROGRESS
failureReason (string) --
If a recommender update fails, the reason behind the failure.
modelMetrics (dict) --
Provides evaluation metrics that help you determine the performance of a recommender. For more information, see Evaluating a recommender.
(string) --
(float) --
{'batchInferenceJobs': {'batchInferenceJobMode': 'BATCH_INFERENCE | '
'THEME_GENERATION'}}
Gets a list of the batch inference jobs that have been performed off of a solution version.
See also: AWS API Documentation
Request Syntax
client.list_batch_inference_jobs(
solutionVersionArn='string',
nextToken='string',
maxResults=123
)
string
The Amazon Resource Name (ARN) of the solution version from which the batch inference jobs were created.
string
The token to request the next page of results.
integer
The maximum number of batch inference job results to return in each page. The default value is 100.
dict
Response Syntax
{
'batchInferenceJobs': [
{
'batchInferenceJobArn': 'string',
'jobName': 'string',
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1),
'failureReason': 'string',
'solutionVersionArn': 'string',
'batchInferenceJobMode': 'BATCH_INFERENCE'|'THEME_GENERATION'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
batchInferenceJobs (list) --
A list containing information on each job that is returned.
(dict) --
A truncated version of the BatchInferenceJob. The ListBatchInferenceJobs operation returns a list of batch inference job summaries.
batchInferenceJobArn (string) --
The Amazon Resource Name (ARN) of the batch inference job.
jobName (string) --
The name of the batch inference job.
status (string) --
The status of the batch inference job. The status is one of the following values:
PENDING
IN PROGRESS
ACTIVE
CREATE FAILED
creationDateTime (datetime) --
The time at which the batch inference job was created.
lastUpdatedDateTime (datetime) --
The time at which the batch inference job was last updated.
failureReason (string) --
If the batch inference job failed, the reason for the failure.
solutionVersionArn (string) --
The ARN of the solution version used by the batch inference job.
batchInferenceJobMode (string) --
The job's mode.
nextToken (string) --
The token to use to retrieve the next page of results. The value is null when there are no more results to return.
{'recommenders': {'recommenderConfig': {'enableMetadataWithRecommendations': 'boolean'}}}
Returns a list of recommenders in a given Domain dataset group. When a Domain dataset group is not specified, all the recommenders associated with the account are listed. The response provides the properties for each recommender, including the Amazon Resource Name (ARN). For more information on recommenders, see CreateRecommender.
See also: AWS API Documentation
Request Syntax
client.list_recommenders(
datasetGroupArn='string',
nextToken='string',
maxResults=123
)
string
The Amazon Resource Name (ARN) of the Domain dataset group to list the recommenders for. When a Domain dataset group is not specified, all the recommenders associated with the account are listed.
string
A token returned from the previous call to ListRecommenders for getting the next set of recommenders (if they exist).
integer
The maximum number of recommenders to return.
dict
Response Syntax
{
'recommenders': [
{
'name': 'string',
'recommenderArn': 'string',
'datasetGroupArn': 'string',
'recipeArn': 'string',
'recommenderConfig': {
'itemExplorationConfig': {
'string': 'string'
},
'minRecommendationRequestsPerSecond': 123,
'trainingDataConfig': {
'excludedDatasetColumns': {
'string': [
'string',
]
}
},
'enableMetadataWithRecommendations': True|False
},
'status': 'string',
'creationDateTime': datetime(2015, 1, 1),
'lastUpdatedDateTime': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
recommenders (list) --
A list of the recommenders.
(dict) --
Provides a summary of the properties of the recommender.
name (string) --
The name of the recommender.
recommenderArn (string) --
The Amazon Resource Name (ARN) of the recommender.
datasetGroupArn (string) --
The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender.
recipeArn (string) --
The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for.
recommenderConfig (dict) --
The configuration details of the recommender.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).
(string) --
(string) --
minRecommendationRequestsPerSecond (integer) --
Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.
trainingDataConfig (dict) --
Specifies the training data configuration to use when creating a domain recommender.
excludedDatasetColumns (dict) --
Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.
(string) --
(list) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the recommender. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
status (string) --
The status of the recommender. A recommender can be in one of the following states:
CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED
STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE
DELETE PENDING > DELETE IN_PROGRESS
creationDateTime (datetime) --
The date and time (in Unix format) that the recommender was created.
lastUpdatedDateTime (datetime) --
The date and time (in Unix format) that the recommender was last updated.
nextToken (string) --
A token for getting the next set of recommenders (if they exist).
{'campaignConfig': {'enableMetadataWithRecommendations': 'boolean'}}
Updates a campaign to deploy a retrained solution version with an existing campaign, change your campaign's minProvisionedTPS , or modify your campaign's configuration, such as the exploration configuration.
To update a campaign, the campaign status must be ACTIVE or CREATE FAILED. Check the campaign status using the DescribeCampaign operation.
Note
You can still get recommendations from a campaign while an update is in progress. The campaign will use the previous solution version and campaign configuration to generate recommendations until the latest campaign update status is Active .
For more information about updating a campaign, including code samples, see Updating a campaign. For more information about campaigns, see Creating a campaign.
See also: AWS API Documentation
Request Syntax
client.update_campaign(
campaignArn='string',
solutionVersionArn='string',
minProvisionedTPS=123,
campaignConfig={
'itemExplorationConfig': {
'string': 'string'
},
'enableMetadataWithRecommendations': True|False
}
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the campaign.
string
The ARN of a new solution version to deploy.
integer
Specifies the requested minimum provisioned transactions (recommendations) per second that Amazon Personalize will support. A high minProvisionedTPS will increase your bill. We recommend starting with 1 for minProvisionedTPS (the default). Track your usage using Amazon CloudWatch metrics, and increase the minProvisionedTPS as necessary.
dict
The configuration details of a campaign.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your solution uses the User-Personalization recipe.
(string) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the campaign. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
dict
Response Syntax
{
'campaignArn': 'string'
}
Response Structure
(dict) --
campaignArn (string) --
The same campaign ARN as given in the request.
{'recommenderConfig': {'enableMetadataWithRecommendations': 'boolean'}}
Updates the recommender to modify the recommender configuration. If you update the recommender to modify the columns used in training, Amazon Personalize automatically starts a full retraining of the models backing your recommender. While the update completes, you can still get recommendations from the recommender. The recommender uses the previous configuration until the update completes. To track the status of this update, use the latestRecommenderUpdate returned in the DescribeRecommender operation.
See also: AWS API Documentation
Request Syntax
client.update_recommender(
recommenderArn='string',
recommenderConfig={
'itemExplorationConfig': {
'string': 'string'
},
'minRecommendationRequestsPerSecond': 123,
'trainingDataConfig': {
'excludedDatasetColumns': {
'string': [
'string',
]
}
},
'enableMetadataWithRecommendations': True|False
}
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the recommender to modify.
dict
[REQUIRED]
The configuration details of the recommender.
itemExplorationConfig (dict) --
Specifies the exploration configuration hyperparameters, including explorationWeight and explorationItemAgeCutOff , you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. Provide itemExplorationConfig data only if your recommenders generate personalized recommendations for a user (not popular items or similar items).
(string) --
(string) --
minRecommendationRequestsPerSecond (integer) --
Specifies the requested minimum provisioned recommendation requests per second that Amazon Personalize will support. A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary.
trainingDataConfig (dict) --
Specifies the training data configuration to use when creating a domain recommender.
excludedDatasetColumns (dict) --
Specifies the columns to exclude from training. Each key is a dataset type, and each value is a list of columns. Exclude columns to control what data Amazon Personalize uses to generate recommendations. For example, you might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.
(string) --
(list) --
(string) --
enableMetadataWithRecommendations (boolean) --
Whether metadata with recommendations is enabled for the recommender. If enabled, you can specify the columns from your Items dataset in your request for recommendations. Amazon Personalize returns this data for each item in the recommendation response.
If you enable metadata in recommendations, you will incur additional costs. For more information, see Amazon Personalize pricing.
dict
Response Syntax
{
'recommenderArn': 'string'
}
Response Structure
(dict) --
recommenderArn (string) --
The same recommender Amazon Resource Name (ARN) as given in the request.