campaigns

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

Overview

Name	campaigns
Type	Resource
Id	aws.personalize.campaigns

Fields

The following fields are returned by SELECT queries:

describe_campaign

Name	Datatype	Description
name	string	The name of the campaign. (pattern: <code>^[a-zA-Z0-9][a-zA-Z0-9-_]*</code>)
campaign_arn	string	The Amazon Resource Name (ARN) of the campaign. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
campaign_config	object	The configuration details of a campaign.
creation_date_time	string (date-time)	The date and time (in Unix format) that the campaign was created.
failure_reason	string	If a campaign fails, the reason behind the failure.
last_updated_date_time	string (date-time)	The date and time (in Unix format) that the campaign was last updated.
latest_campaign_update	object	Provides a summary of the properties of a campaign update. For a complete listing, call the DescribeCampaign API. The latestCampaignUpdate field is only returned when the campaign has had at least one UpdateCampaign call.
min_provisioned_tps	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.
solution_version_arn	string	The Amazon Resource Name (ARN) of the solution version the campaign uses. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
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

list_campaigns

Name	Datatype	Description
name	string	The name of the campaign. (pattern: <code>^[a-zA-Z0-9][a-zA-Z0-9-_]*</code>)
campaign_arn	string	The Amazon Resource Name (ARN) of the campaign. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
creation_date_time	string (date-time)	The date and time (in Unix time) that the campaign was created.
failure_reason	string	If a campaign fails, the reason behind the failure.
last_updated_date_time	string (date-time)	The date and time (in Unix time) that the campaign was last updated.
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

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_campaign	select	region		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.
list_campaigns	select	region		Returns a list of campaigns that use the given solution. When a solution is not specified, all the campaigns associated with the account are listed. The response provides the properties for each campaign, including the Amazon Resource Name (ARN). For more information on campaigns, see CreateCampaign.
create_campaign	insert	region, name, solutionVersionArn		You incur campaign costs while it is active. To avoid unnecessary costs, make sure to delete the campaign when you are finished. For information about campaign costs, see Amazon Personalize pricing. 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 A high minProvisionedTPS will increase your cost. We recommend starting with 1 for minProvisionedTPS (the default). Track your usage using Amazon CloudWatch metrics, and increase the minProvisionedTPS as necessary. When you create an Amazon Personalize campaign, you can specify the minimum provisioned transactions per second (minProvisionedTPS) for the campaign. This is the baseline transaction throughput for the campaign provisioned by Amazon Personalize. It sets the minimum billing charge for the campaign while it is active. A transaction is a single GetRecommendations or GetPersonalizedRanking request. The default minProvisionedTPS is 1. If your TPS increases beyond the 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. When your traffic reduces, capacity returns to the minProvisionedTPS. You are charged for the the minimum provisioned TPS or, if your requests exceed the minProvisionedTPS, the actual TPS. The actual TPS is the total number of recommendation requests you make. We recommend starting with a low minProvisionedTPS, track your usage using Amazon CloudWatch metrics, and then increase the minProvisionedTPS as necessary. For more information about campaign costs, see Amazon Personalize pricing. 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. Wait until the status of the campaign is ACTIVE before asking the campaign for recommendations. Related APIs ListCampaigns DescribeCampaign UpdateCampaign DeleteCampaign
update_campaign	update	region, campaignArn		Updates a campaign to deploy a retrained solution version with an existing campaign, change your campaign's minProvisionedTPS, or modify your campaign's configuration. For example, you can set enableMetadataWithRecommendations to true for an existing campaign. To update a campaign to start automatically using the latest solution version, specify the following: For the SolutionVersionArn parameter, specify the Amazon Resource Name (ARN) of your solution in SolutionArn/$LATEST format. In the campaignConfig, set syncWithLatestSolutionVersion to true. To update a campaign, the campaign status must be ACTIVE or CREATE FAILED. Check the campaign status using the DescribeCampaign operation. 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.
delete_campaign	delete	region		Removes a campaign by deleting the solution deployment. The solution that the campaign is based on is not deleted and can be redeployed when needed. A deleted campaign can no longer be specified in a GetRecommendations request. For information on creating campaigns, see CreateCampaign.

Parameters

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

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_campaign

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.

SELECT
name,
campaign_arn,
campaign_config,
creation_date_time,
failure_reason,
last_updated_date_time,
latest_campaign_update,
min_provisioned_tps,
solution_version_arn,
status
FROM aws.personalize.campaigns
WHERE region = '{{ region }}' -- required
;

list_campaigns

Returns a list of campaigns that use the given solution. When a solution is not specified, all the campaigns associated with the account are listed. The response provides the properties for each campaign, including the Amazon Resource Name (ARN). For more information on campaigns, see CreateCampaign.

SELECT
name,
campaign_arn,
creation_date_time,
failure_reason,
last_updated_date_time,
status
FROM aws.personalize.campaigns
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_campaign

You incur campaign costs while it is active. To avoid unnecessary costs, make sure to delete the campaign when you are finished. For information about campaign costs, see Amazon Personalize pricing. 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 A high minProvisionedTPS will increase your cost. We recommend starting with 1 for minProvisionedTPS (the default). Track your usage using Amazon CloudWatch metrics, and increase the minProvisionedTPS as necessary. When you create an Amazon Personalize campaign, you can specify the minimum provisioned transactions per second (minProvisionedTPS) for the campaign. This is the baseline transaction throughput for the campaign provisioned by Amazon Personalize. It sets the minimum billing charge for the campaign while it is active. A transaction is a single GetRecommendations or GetPersonalizedRanking request. The default minProvisionedTPS is 1. If your TPS increases beyond the 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. When your traffic reduces, capacity returns to the minProvisionedTPS. You are charged for the the minimum provisioned TPS or, if your requests exceed the minProvisionedTPS, the actual TPS. The actual TPS is the total number of recommendation requests you make. We recommend starting with a low minProvisionedTPS, track your usage using Amazon CloudWatch metrics, and then increase the minProvisionedTPS as necessary. For more information about campaign costs, see Amazon Personalize pricing. 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. Wait until the status of the campaign is ACTIVE before asking the campaign for recommendations. Related APIs ListCampaigns DescribeCampaign UpdateCampaign DeleteCampaign

INSERT INTO aws.personalize.campaigns (
name,
solutionVersionArn,
minProvisionedTPS,
campaignConfig,
tags,
region
)
SELECT 
'{{ name }}' /* required */,
'{{ solutionVersionArn }}' /* required */,
{{ minProvisionedTPS }},
'{{ campaignConfig }}',
'{{ tags }}',
'{{ region }}'
RETURNING
campaign_arn
;

Manifest

# Description fields are for documentation purposes
- name: campaigns
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the campaigns resource.
  - name: name
    value: "{{ name }}"
    description: |
      A name for the new campaign. The campaign name must be unique within your account.
  - name: solutionVersionArn
    value: "{{ solutionVersionArn }}"
    description: |
      The Amazon Resource Name (ARN) of the trained model to deploy with the campaign. To specify the latest solution version of your solution, specify the ARN of your solution in SolutionArn/$LATEST format. You must use this format if you set syncWithLatestSolutionVersion to True in the CampaignConfig. To deploy a model that isn't the latest solution version of your solution, specify the ARN of the solution version. For more information about automatic campaign updates, see Enabling automatic campaign updates.
  - name: minProvisionedTPS
    value: {{ minProvisionedTPS }}
    description: |
      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.
  - name: campaignConfig
    description: |
      The configuration details of a campaign.
    value:
      itemExplorationConfig: "{{ itemExplorationConfig }}"
      enableMetadataWithRecommendations: {{ enableMetadataWithRecommendations }}
      syncWithLatestSolutionVersion: {{ syncWithLatestSolutionVersion }}
      rankingInfluence: "{{ rankingInfluence }}"
  - name: tags
    description: |
      A list of tags to apply to the campaign.
    value:
      - tagKey: "{{ tagKey }}"
        tagValue: "{{ tagValue }}"

UPDATE examples

update_campaign

Updates a campaign to deploy a retrained solution version with an existing campaign, change your campaign's minProvisionedTPS, or modify your campaign's configuration. For example, you can set enableMetadataWithRecommendations to true for an existing campaign. To update a campaign to start automatically using the latest solution version, specify the following: For the SolutionVersionArn parameter, specify the Amazon Resource Name (ARN) of your solution in SolutionArn/$LATEST format. In the campaignConfig, set syncWithLatestSolutionVersion to true. To update a campaign, the campaign status must be ACTIVE or CREATE FAILED. Check the campaign status using the DescribeCampaign operation. 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.

UPDATE aws.personalize.campaigns
SET 
campaignArn = '{{ campaignArn }}',
solutionVersionArn = '{{ solutionVersionArn }}',
minProvisionedTPS = {{ minProvisionedTPS }},
campaignConfig = '{{ campaignConfig }}'
WHERE 
region = '{{ region }}' --required
AND campaignArn = '{{ campaignArn }}' --required
RETURNING
campaign_arn;

DELETE examples

delete_campaign

Removes a campaign by deleting the solution deployment. The solution that the campaign is based on is not deleted and can be redeployed when needed. A deleted campaign can no longer be specified in a GetRecommendations request. For information on creating campaigns, see CreateCampaign.

DELETE FROM aws.personalize.campaigns
WHERE region = '{{ region }}' --required
;