openapi: 3.1.0
info:
  title: Google Cloud Dataflow Debug Messages API
  description: Manages Google Cloud Dataflow projects on Google Cloud Platform for creating and managing data processing pipelines, including job submission, monitoring, and resource management for both batch and streaming workloads.
  version: v1b3
  termsOfService: https://cloud.google.com/terms
  contact:
    name: Google Cloud Support
    url: https://cloud.google.com/dataflow/docs/support
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://dataflow.googleapis.com
  description: Google Cloud Dataflow API production endpoint
security:
- oauth2: []
- apiKey: []
tags:
- name: Messages
  description: Operations for retrieving job status messages and logs.
paths:
  /v1b3/projects/{projectId}/jobs/{jobId}/messages:
    get:
      operationId: listProjectJobMessages
      summary: Google Cloud Dataflow List messages for a Dataflow job in a project
      description: Retrieves the status messages for a specified Dataflow job in the given project. Messages include informational updates, warnings, and errors generated during job execution.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/jobId'
      - name: minimumImportance
        in: query
        description: Filter to return only messages with at least this importance level.
        schema:
          $ref: '#/components/schemas/JobMessageImportance'
      - name: startTime
        in: query
        description: Return messages with timestamps greater than or equal to this value.
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        description: Return messages with timestamps less than this value.
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/location'
      responses:
        '200':
          description: Successful response containing the list of job messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobMessagesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1b3/projects/{projectId}/locations/{location}/jobs/{jobId}/messages:
    get:
      operationId: listLocationJobMessages
      summary: Google Cloud Dataflow List messages for a Dataflow job in a specific location
      description: Retrieves the status messages for a specified Dataflow job in the given project and regional location. Messages include informational updates, warnings, and errors generated during job execution.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/locationPath'
      - $ref: '#/components/parameters/jobId'
      - name: minimumImportance
        in: query
        description: Filter to return only messages with at least this importance level.
        schema:
          $ref: '#/components/schemas/JobMessageImportance'
      - name: startTime
        in: query
        description: Return messages with timestamps greater than or equal to this value.
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        description: Return messages with timestamps less than this value.
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successful response containing the list of job messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobMessagesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    AutoscalingEvent:
      type: object
      description: A structured message reporting an autoscaling decision made by the Dataflow service.
      properties:
        currentNumWorkers:
          type: string
          format: int64
          description: The current number of workers the job has.
        targetNumWorkers:
          type: string
          format: int64
          description: The target number of workers the worker pool wants to resize to use.
        eventType:
          type: string
          description: The type of autoscaling event.
          enum:
          - TYPE_UNKNOWN
          - TARGET_NUM_WORKERS_CHANGED
          - CURRENT_NUM_WORKERS_CHANGED
          - ACTUATION_FAILURE
          - NO_CHANGE
        description:
          $ref: '#/components/schemas/StructuredMessage'
        time:
          type: string
          format: date-time
          description: The time this event was emitted to indicate a new target or current num_workers value.
        workerPool:
          type: string
          description: A short and friendly name for the worker pool this event refers to.
    ListJobMessagesResponse:
      type: object
      description: Response to a request to list job messages. This may be a partial response, requiring pagination.
      properties:
        jobMessages:
          type: array
          description: Messages in time order.
          items:
            $ref: '#/components/schemas/JobMessage'
        autoscalingEvents:
          type: array
          description: Autoscaling events in time order.
          items:
            $ref: '#/components/schemas/AutoscalingEvent'
        nextPageToken:
          type: string
          description: The token to retrieve the next page of results.
    Status:
      type: object
      description: The Status type defines a logical error model, compatible with gRPC and Google API error conventions.
      properties:
        code:
          type: integer
          format: int32
          description: The status code, which should be an enum value of google.rpc.Code.
        message:
          type: string
          description: A developer-facing error message, which should be in English.
        details:
          type: array
          description: A list of messages that carry the error details.
          items:
            type: object
            additionalProperties: true
    StructuredMessageParameter:
      type: object
      description: Structured data associated with this message.
      properties:
        key:
          type: string
          description: Key or name for this parameter.
        value:
          description: Value for this parameter.
    JobMessageImportance:
      type: string
      description: Indicates the importance of a job message, used for filtering.
      enum:
      - JOB_MESSAGE_IMPORTANCE_UNKNOWN
      - JOB_MESSAGE_DEBUG
      - JOB_MESSAGE_DETAILED
      - JOB_MESSAGE_BASIC
      - JOB_MESSAGE_WARNING
      - JOB_MESSAGE_ERROR
    JobMessage:
      type: object
      description: A particular message pertaining to a Dataflow job, such as a status update, error notification, or warning.
      properties:
        id:
          type: string
          description: Deprecated.
        time:
          type: string
          format: date-time
          description: The timestamp of the message.
        messageText:
          type: string
          description: The text of the message.
        messageImportance:
          $ref: '#/components/schemas/JobMessageImportance'
    StructuredMessage:
      type: object
      description: A rich message format, including a human readable string.
      properties:
        messageText:
          type: string
          description: Human-readable version of message.
        messageKey:
          type: string
          description: Identifier for this message type.
        parameters:
          type: array
          description: The structured data associated with this message.
          items:
            $ref: '#/components/schemas/StructuredMessageParameter'
  responses:
    Forbidden:
      description: The caller does not have sufficient permissions to perform this operation. Verify IAM roles and permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    Unauthorized:
      description: Authentication credentials were missing or invalid. Provide valid OAuth 2.0 credentials or API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    InternalServerError:
      description: An internal server error occurred. Retry the request using exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    NotFound:
      description: The requested resource was not found. Verify the project ID, job ID, or other resource identifiers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    TooManyRequests:
      description: The request was rate-limited. Retry the request after a brief delay using exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    BadRequest:
      description: The request was invalid or malformed. Check the request parameters and body for errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
  parameters:
    pageToken:
      name: pageToken
      in: query
      description: A token identifying the page of results to return. Set this to the nextPageToken value returned by a previous list request.
      schema:
        type: string
    projectId:
      name: projectId
      in: path
      required: true
      description: The ID of the Google Cloud project that owns the job.
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      description: The maximum number of results to return per page. If unspecified, the server will determine the number of results to return.
      schema:
        type: integer
        format: int32
    location:
      name: location
      in: query
      description: The regional endpoint for the request, such as us-central1 or europe-west1.
      schema:
        type: string
    locationPath:
      name: location
      in: path
      required: true
      description: The regional endpoint where the job resides, such as us-central1 or europe-west1.
      schema:
        type: string
    jobId:
      name: jobId
      in: path
      required: true
      description: The unique identifier of the Dataflow job.
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for Google Cloud APIs.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/cloud-platform: Full access to all Google Cloud resources.
            https://www.googleapis.com/auth/compute: View and manage Google Compute Engine resources.
            https://www.googleapis.com/auth/compute.readonly: View Google Compute Engine resources.
    apiKey:
      type: apiKey
      name: key
      in: query
      description: API key for identifying the calling project.
externalDocs:
  description: Google Cloud Dataflow REST API Reference
  url: https://cloud.google.com/dataflow/docs/reference/rest