Amazon Personalize Personalize Batch Inference Job API

openapi: 3.2.0
info:
  title: Amazon Personalize Batch Inference Job API
  version: '2018-05-22'
  description: Generated from AWS's published Smithy model for Amazon Personalize. 3 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://personalize.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Batch Inference Job
paths:
  /#CreateBatchInferenceJob:
    post:
      operationId: CreateBatchInferenceJob
      summary: Create Batch Inference Job
      description: 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.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateBatchInferenceJobResponse'
        '400':
          description: InvalidInputException; TooManyTagsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '409':
          description: LimitExceededException; ResourceInUseException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '403':
          description: ResourceAlreadyExistsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceAlreadyExistsException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonPersonalize.CreateBatchInferenceJob
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateBatchInferenceJobRequest'
      tags:
      - Batch Inference Job
  /#DescribeBatchInferenceJob:
    post:
      operationId: DescribeBatchInferenceJob
      summary: Describe Batch Inference Job
      description: 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.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeBatchInferenceJobResponse'
        '400':
          description: InvalidInputException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonPersonalize.DescribeBatchInferenceJob
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeBatchInferenceJobRequest'
      tags:
      - Batch Inference Job
  /#ListBatchInferenceJobs:
    post:
      operationId: ListBatchInferenceJobs
      summary: List Batch Inference Jobs
      description: Gets a list of the batch inference jobs that have been performed off of a solution version.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListBatchInferenceJobsResponse'
        '400':
          description: InvalidInputException; InvalidNextTokenException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidInputException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonPersonalize.ListBatchInferenceJobs
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListBatchInferenceJobsRequest'
      tags:
      - Batch Inference Job
components:
  schemas:
    BatchInferenceJobOutput:
      type: object
      properties:
        s3DataDestination:
          $ref: '#/components/schemas/S3DataConfig'
      required:
      - s3DataDestination
    BatchInferenceJobInput:
      type: object
      properties:
        s3DataSource:
          $ref: '#/components/schemas/S3DataConfig'
      required:
      - s3DataSource
    ListBatchInferenceJobsResponse:
      type: object
      properties:
        batchInferenceJobs:
          type: array
          items:
            $ref: '#/components/schemas/BatchInferenceJobSummary'
          description: A list containing information on each job that is returned.
        nextToken:
          type: string
          description: The token to use to retrieve the next page of results. The value is null when there are no more results to return.
    DescribeBatchInferenceJobResponse:
      type: object
      properties:
        batchInferenceJob:
          $ref: '#/components/schemas/BatchInferenceJob'
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
    ResourceAlreadyExistsException:
      type: object
      properties:
        message:
          type: string
    BatchInferenceJob:
      type: object
      properties:
        jobName:
          type: string
          description: The name of the batch inference job.
        batchInferenceJobArn:
          type: string
          description: The Amazon Resource Name (ARN) of the batch inference job.
        filterArn:
          type: string
          description: The ARN of the filter used on the batch inference job.
        failureReason:
          type: string
          description: If the batch inference job failed, the reason for the failure.
        solutionVersionArn:
          type: string
          description: The Amazon Resource Name (ARN) of the solution version from which the batch inference job was created.
        numResults:
          type: integer
          description: The number of recommendations generated by the batch inference job. This number includes the error messages generated for failed input records.
        jobInput:
          $ref: '#/components/schemas/BatchInferenceJobInput'
        jobOutput:
          $ref: '#/components/schemas/BatchInferenceJobOutput'
        batchInferenceJobConfig:
          $ref: '#/components/schemas/BatchInferenceJobConfig'
        roleArn:
          type: string
          description: The ARN of the Amazon Identity and Access Management (IAM) role that requested the batch inference job.
        batchInferenceJobMode:
          type: string
          enum:
          - BATCH_INFERENCE
          - THEME_GENERATION
          description: The job's mode.
        themeGenerationConfig:
          $ref: '#/components/schemas/ThemeGenerationConfig'
        status:
          type: string
          description: 'The status of the batch inference job. The status is one of the following values: PENDING IN PROGRESS ACTIVE CREATE FAILED'
        creationDateTime:
          type: string
          format: date-time
          description: The time at which the batch inference job was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: The time at which the batch inference job was last updated.
    DescribeBatchInferenceJobRequest:
      type: object
      properties:
        batchInferenceJobArn:
          type: string
          description: The ARN of the batch inference job to describe.
      required:
      - batchInferenceJobArn
    BatchInferenceJobConfig:
      type: object
      properties:
        itemExplorationConfig:
          type: object
          additionalProperties:
            type: string
          description: 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.
        rankingInfluence:
          type: object
          additionalProperties:
            type: number
          description: A map of ranking influence values for POPULARITY and FRESHNESS. For each key, specify a numerical value between 0.0 and 1.0 that determines how much influence that ranking factor has on the final recommendations. A value closer to 1.0 gives more weight to the factor, while a value closer to 0.0 reduces its influence.
    LimitExceededException:
      type: object
      properties:
        message:
          type: string
    CreateBatchInferenceJobRequest:
      type: object
      properties:
        jobName:
          type: string
          description: The name of the batch inference job to create.
        solutionVersionArn:
          type: string
          description: The Amazon Resource Name (ARN) of the solution version that will be used to generate the batch inference recommendations.
        filterArn:
          type: string
          description: The ARN of the filter to apply to the batch inference job. For more information on using filters, see Filtering batch recommendations.
        numResults:
          type: integer
          description: The number of recommendations to retrieve.
        jobInput:
          $ref: '#/components/schemas/BatchInferenceJobInput'
        jobOutput:
          $ref: '#/components/schemas/BatchInferenceJobOutput'
        roleArn:
          type: string
          description: 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.
        batchInferenceJobConfig:
          $ref: '#/components/schemas/BatchInferenceJobConfig'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: A list of tags to apply to the batch inference job.
        batchInferenceJobMode:
          type: string
          enum:
          - BATCH_INFERENCE
          - THEME_GENERATION
          description: 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.
        themeGenerationConfig:
          $ref: '#/components/schemas/ThemeGenerationConfig'
      required:
      - jobName
      - solutionVersionArn
      - jobInput
      - jobOutput
      - roleArn
    Tag:
      type: object
      properties:
        tagKey:
          type: string
          description: 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:
          type: string
          description: The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).
      required:
      - tagKey
      - tagValue
    InvalidInputException:
      type: object
      properties:
        message:
          type: string
    BatchInferenceJobSummary:
      type: object
      properties:
        batchInferenceJobArn:
          type: string
          description: The Amazon Resource Name (ARN) of the batch inference job.
        jobName:
          type: string
          description: The name of the batch inference job.
        status:
          type: string
          description: 'The status of the batch inference job. The status is one of the following values: PENDING IN PROGRESS ACTIVE CREATE FAILED'
        creationDateTime:
          type: string
          format: date-time
          description: The time at which the batch inference job was created.
        lastUpdatedDateTime:
          type: string
          format: date-time
          description: The time at which the batch inference job was last updated.
        failureReason:
          type: string
          description: If the batch inference job failed, the reason for the failure.
        solutionVersionArn:
          type: string
          description: The ARN of the solution version used by the batch inference job.
        batchInferenceJobMode:
          type: string
          enum:
          - BATCH_INFERENCE
          - THEME_GENERATION
          description: The job's mode.
    S3DataConfig:
      type: object
      properties:
        path:
          type: string
          description: The file path of the Amazon S3 bucket.
        kmsKeyArn:
          type: string
          description: 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.
      required:
      - path
    FieldsForThemeGeneration:
      type: object
      properties:
        itemName:
          type: string
          description: The name of the Items dataset column that stores the name of each item in the dataset.
      required:
      - itemName
    ListBatchInferenceJobsRequest:
      type: object
      properties:
        solutionVersionArn:
          type: string
          description: The Amazon Resource Name (ARN) of the solution version from which the batch inference jobs were created.
        nextToken:
          type: string
          description: The token to request the next page of results.
        maxResults:
          type: integer
          description: The maximum number of batch inference job results to return in each page. The default value is 100.
    CreateBatchInferenceJobResponse:
      type: object
      properties:
        batchInferenceJobArn:
          type: string
          description: The ARN of the batch inference job.
    ThemeGenerationConfig:
      type: object
      properties:
        fieldsForThemeGeneration:
          $ref: '#/components/schemas/FieldsForThemeGeneration'
      required:
      - fieldsForThemeGeneration
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: personalize
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/personalize/service/2018-05-22/personalize-2018-05-22.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)