META-INF.smithy.personalizeevents.smithy Maven / Gradle / Ivy

Go to download
$version: "2.0"

metadata suppressions = [
    {
        id: "HttpMethodSemantics"
        namespace: "*"
    }
    {
        id: "HttpResponseCodeSemantics"
        namespace: "*"
    }
    {
        id: "PaginatedTrait"
        namespace: "*"
    }
    {
        id: "HttpHeaderTrait"
        namespace: "*"
    }
    {
        id: "HttpUriConflict"
        namespace: "*"
    }
    {
        id: "Service"
        namespace: "*"
    }
]

namespace com.amazonaws.personalizeevents

use aws.api#service
use aws.auth#sigv4
use aws.protocols#restJson1

/// Amazon Personalize can consume real-time user event data, such as stream or click data, and use
///       it for model training either alone or combined with historical data. For more information see
///       Recording Events.
@service(
    sdkId: "Personalize Events"
    arnNamespace: "personalize"
    cloudFormationName: "PersonalizeEvents"
    cloudTrailEventSource: "personalizeevents.amazonaws.com"
    endpointPrefix: "personalize-events"
)
@sigv4(
    name: "personalize"
)
@restJson1
@title("Amazon Personalize Events")
service AmazonPersonalizeEvents {
    version: "2018-03-22"
    operations: [
        PutEvents
        PutItems
        PutUsers
    ]
}

/// Records user interaction event data. For more information see
///       Recording Events.
@http(
    method: "POST"
    uri: "/events"
    code: 200
)
operation PutEvents {
    input: PutEventsRequest
    output: Unit
    errors: [
        InvalidInputException
    ]
}

/// Adds one or more items to an Items dataset. For more information see
///       Importing Items Incrementally.
///      
@http(
    method: "POST"
    uri: "/items"
    code: 200
)
operation PutItems {
    input: PutItemsRequest
    output: Unit
    errors: [
        InvalidInputException
        ResourceInUseException
        ResourceNotFoundException
    ]
}

/// Adds one or more users to a Users dataset. For more information see
///       Importing Users Incrementally.
@http(
    method: "POST"
    uri: "/users"
    code: 200
)
operation PutUsers {
    input: PutUsersRequest
    output: Unit
    errors: [
        InvalidInputException
        ResourceInUseException
        ResourceNotFoundException
    ]
}

/// Represents user interaction event information sent using the
///       PutEvents API.
@sensitive
structure Event {
    /// An ID associated with the event. If an event ID is not provided, Amazon Personalize generates
    ///       a unique ID for the event. An event ID is not used as an input to the model. Amazon Personalize uses
    ///       the event ID to distinquish unique events. Any subsequent events after the first with the
    ///       same event ID are not used in model training.
    eventId: StringType
    /// The type of event, such as click or download. This property corresponds to the EVENT_TYPE
    ///       field of your Interactions schema and depends on the types of events you are tracking.
    @required
    eventType: StringType
    /// The event value that corresponds to the EVENT_VALUE field of the Interactions schema.
    eventValue: FloatType
    /// The item ID key that corresponds to the ITEM_ID field of the Interactions schema.
    itemId: ItemId
    /// A string map of event-specific data that you might choose to record. For example, if a
    ///       user rates a movie on your site, other than movie ID (itemId) and rating (eventValue)
    ///       , you might also send the number of movie ratings made by the user.
    ///          Each item in the map consists of a key-value pair. For example,
    ///          
    ///             {"numberOfRatings": "12"}
    ///          
    ///          The keys use camel case names that match the fields in the Interactions
    ///       schema. In the above example, the numberOfRatings would match the
    ///       'NUMBER_OF_RATINGS' field defined in the Interactions schema.
    properties: SynthesizedJsonEventPropertiesJSON
    /// The timestamp (in Unix time) on the client side when the event occurred.
    @required
    sentAt: Date
    /// The ID of the list of recommendations that contains the item the user interacted with. Provide a recommendationId to have Amazon Personalize implicitly record the
    ///       recommendations you show your user as impressions data. Or provide a recommendationId if you use a metric attribution to measure the impact of recommendations.
    ///     
    ///          
    ///       For more information on recording impressions data, see Recording impressions data.
    ///       For more information on creating a metric attribution see Measuring impact of recommendations.
    ///     
    recommendationId: RecommendationId
    /// A list of item IDs that represents the sequence of items you have shown the user. For example, ["itemId1", "itemId2", "itemId3"]. Provide a list of
    ///       items to manually record impressions data for an event. For more information on recording impressions data,
    ///       see Recording impressions data. 
    impression: Impression
    /// Contains information about the metric attribution associated with an event. For more information about metric attributions, see Measuring impact of recommendations.
    metricAttribution: MetricAttribution
}

/// Provide a valid value for the field or parameter.
@error("client")
@httpError(400)
structure InvalidInputException {
    message: ErrorMessage
}

/// Represents item metadata added to an Items dataset using the
///       PutItems API. For more information see
///       Importing Items Incrementally.
///     
structure Item {
    /// The ID associated with the item.
    @required
    itemId: StringType
    /// A string map of item-specific metadata. Each element in the map consists of a key-value pair.
    ///       For example, {"numberOfRatings": "12"}.
    ///          The keys use camel case names that match the fields in the schema for the Items
    ///       dataset. In the previous example, the numberOfRatings matches the
    ///       'NUMBER_OF_RATINGS' field defined in the Items schema. For categorical string data, to include multiple categories for a single item,
    ///       separate each category with a pipe separator (|). For example, \"Horror|Action\".
    properties: SynthesizedJsonItemProperties
}

/// Contains information about a metric attribution associated with an event. For more information about metric attributions, see Measuring impact of recommendations.
structure MetricAttribution {
    /// The source of the event, such as a third party.
    @required
    eventAttributionSource: EventAttributionSource
}

@input
structure PutEventsRequest {
    /// The tracking ID for the event.
    ///       The ID is generated by a call to the
    ///       CreateEventTracker API.
    @required
    trackingId: StringType
    /// The user associated with the event.
    userId: UserId
    /// The session ID associated with the user's visit. Your application generates the sessionId when a user first visits your website or uses your application.
    ///       Amazon Personalize uses the sessionId to associate events with the user before they log in. For more information, see
    ///       Recording Events.
    @required
    sessionId: StringType
    /// A list of event data from the session.
    @required
    eventList: EventList
}

@input
structure PutItemsRequest {
    /// The Amazon Resource Name (ARN) of the Items dataset you are adding the item or items to.
    @required
    datasetArn: Arn
    /// A list of item data.
    @required
    items: ItemList
}

@input
structure PutUsersRequest {
    /// The Amazon Resource Name (ARN) of the Users dataset you are adding the user or users to.
    @required
    datasetArn: Arn
    /// A list of user data.
    @required
    users: UserList
}

/// The specified resource is in use.
@error("client")
@httpError(409)
structure ResourceInUseException {
    message: ErrorMessage
}

/// Could not find the specified resource.
@error("client")
@httpError(404)
structure ResourceNotFoundException {
    message: ErrorMessage
}

/// Represents user metadata added to a Users dataset using the
///       PutUsers API. For more information see
///       Importing Users Incrementally.
structure User {
    /// The ID associated with the user.
    @required
    userId: StringType
    /// A string map of user-specific metadata. Each element in the map consists of a key-value pair.
    ///       For example, {"numberOfVideosWatched": "45"}.
    ///          The keys use camel case names that match the fields in the schema for the Users
    ///       dataset. In the previous example, the numberOfVideosWatched matches the
    ///       'NUMBER_OF_VIDEOS_WATCHED' field defined in the Users schema. For categorical string data,
    ///       to include multiple categories for a single user, separate each category with a pipe separator (|).
    ///       For example, \"Member|Frequent shopper\".
    properties: SynthesizedJsonUserProperties
}

@length(
    min: 1
    max: 10
)
list EventList {
    member: Event
}

@length(
    min: 1
    max: 25
)
list Impression {
    member: ItemId
}

@length(
    min: 1
    max: 10
)
list ItemList {
    member: Item
}

@length(
    min: 1
    max: 10
)
list UserList {
    member: User
}

@length(
    min: 0
    max: 256
)
@pattern("^arn:([a-z\\d-]+):personalize:.*:.*:.+$")
string Arn

timestamp Date

string ErrorMessage

@length(
    min: 0
    max: 1024
)
@pattern("^[\\x20-\\x7E]*[\\x21-\\x7E]+[\\x20-\\x7E]*$")
string EventAttributionSource

float FloatType

@length(
    min: 1
    max: 256
)
@sensitive
string ItemId

@length(
    min: 1
    max: 40
)
string RecommendationId

@length(
    min: 1
    max: 256
)
string StringType

@length(
    min: 1
    max: 1024
)
@mediaType("application/json")
@sensitive
string SynthesizedJsonEventPropertiesJSON

@length(
    min: 1
    max: 24262
)
@mediaType("application/json")
@sensitive
string SynthesizedJsonItemProperties

@length(
    min: 1
    max: 4096
)
@mediaType("application/json")
@sensitive
string SynthesizedJsonUserProperties

@length(
    min: 1
    max: 256
)
@sensitive
string UserId