Microsoft Azure Health Data Services Jobs API

openapi: 3.2.0
info:
  title: Azure Health Data Services de-identification service Collection Jobs API
  version: '2024-11-15'
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- AadToken:
  - https://deid.azure.com/.default
tags:
- name: Jobs
paths:
  /jobs:
    get:
      operationId: ListJobs
      summary: List de-identification jobs.
      description: Resource list operation template.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/Azure.Core.MaxPageSizeQueryParameter'
      - $ref: '#/components/parameters/PaginationByTokenQueryParameters.continuationToken'
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeidentificationJob'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
      x-ms-examples:
        List de-identification jobs.:
          $ref: ./examples/ListJobs.json
      x-ms-pageable:
        nextLinkName: nextLink
      tags:
      - Jobs
  /jobs/{name}:
    get:
      operationId: GetJob
      summary: Get a de-identification job.
      description: Resource read operation template.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: name
        in: path
        description: The name of a job.
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 3
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]+[a-zA-Z0-9]$
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeidentificationJob'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
      x-ms-examples:
        Get a de-identification job.:
          $ref: ./examples/GetJob.json
      tags:
      - Jobs
    put:
      operationId: DeidentifyDocuments
      summary: Create a de-identification job.
      description: Long-running resource create or replace operation template.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: name
        in: path
        description: The name of a job.
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 3
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]+[a-zA-Z0-9]$
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            Operation-Location:
              description: The location for monitoring the operation state.
              schema:
                type: string
                format: uri
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeidentificationJob'
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          headers:
            Operation-Location:
              description: The location for monitoring the operation state.
              schema:
                type: string
                format: uri
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeidentificationJob'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
      x-ms-examples:
        Create a de-identification job.:
          $ref: ./examples/DeidentifyDocuments.json
      x-ms-long-running-operation-options:
        final-state-via: original-uri
      x-ms-long-running-operation: true
      tags:
      - Jobs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeidentificationJob'
        description: The resource instance.
        required: true
    delete:
      operationId: DeleteJob
      summary: Delete a de-identification job.
      description: Removes the record of the job from the service. Does not delete any documents.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: name
        in: path
        description: The name of a job.
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 3
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]+[a-zA-Z0-9]$
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
      x-ms-examples:
        Delete a de-identification job.:
          $ref: ./examples/DeleteJob.json
      tags:
      - Jobs
  /jobs/{name}:cancel:
    post:
      operationId: CancelJob
      summary: Cancel a de-identification job.
      description: "Cancels a job that is in progress. \n\nThe job will be marked as canceled and the service will stop processing the job. The service will not delete any documents that have already been processed.\n\nIf the job is already complete, this will have no effect. "
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: name
        in: path
        description: The name of a job.
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 3
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]+[a-zA-Z0-9]$
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeidentificationJob'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
      x-ms-examples:
        Cancel a de-identification job.:
          $ref: ./examples/CancelJob.json
      tags:
      - Jobs
  /jobs/{name}/documents:
    get:
      operationId: ListJobDocuments
      summary: List processed documents within a job.
      description: Resource list operation template.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: name
        in: path
        description: The name of a job.
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 3
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]+[a-zA-Z0-9]$
      - $ref: '#/components/parameters/Azure.Core.MaxPageSizeQueryParameter'
      - $ref: '#/components/parameters/PaginationByTokenQueryParameters.continuationToken'
      - $ref: '#/components/parameters/Azure.Core.ClientRequestIdHeader'
      responses:
        '200':
          description: The request has succeeded.
          headers:
            x-ms-client-request-id:
              description: An opaque, globally-unique, client-generated string identifier for the request.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedDeidentificationDocumentDetails'
        default:
          description: An unexpected error response.
          headers:
            x-ms-error-code:
              description: String error code indicating what went wrong.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
      x-ms-examples:
        List processed documents within a job.:
          $ref: ./examples/ListJobDocuments.json
      x-ms-pageable:
        nextLinkName: nextLink
      tags:
      - Jobs
components:
  schemas:
    Azure.Core.Foundations.OperationState:
      type: string
      description: Enum describing allowed operation states.
      enum:
      - NotStarted
      - Running
      - Succeeded
      - Failed
      - Canceled
      x-ms-enum:
        name: OperationState
        modelAsString: true
        values:
        - name: NotStarted
          value: NotStarted
          description: The operation has not started.
        - name: Running
          value: Running
          description: The operation is in progress.
        - name: Succeeded
          value: Succeeded
          description: The operation has completed successfully.
        - name: Failed
          value: Failed
          description: The operation has failed.
        - name: Canceled
          value: Canceled
          description: The operation has been canceled by the user.
    Azure.Core.Foundations.InnerError:
      type: object
      description: An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
      properties:
        code:
          type: string
          description: One of a server-defined set of error codes.
        innererror:
          $ref: '#/components/schemas/Azure.Core.Foundations.InnerError'
          description: Inner error.
    DeidentificationDocumentDetails:
      type: object
      description: Details of a single document in a job.
      properties:
        id:
          type: string
          description: Id of the document details.
          readOnly: true
        input:
          $ref: '#/components/schemas/DeidentificationDocumentLocation'
          description: Location for the input.
        output:
          $ref: '#/components/schemas/DeidentificationDocumentLocation'
          description: Location for the output.
        status:
          $ref: '#/components/schemas/Azure.Core.Foundations.OperationState'
          description: Status of the document.
        error:
          $ref: '#/components/schemas/Azure.Core.Foundations.Error'
          description: Error when document fails.
      required:
      - id
      - input
      - status
    DeidentificationJob:
      type: object
      description: A job containing a batch of documents to de-identify.
      properties:
        name:
          type: string
          description: The name of a job.
          minLength: 3
          maxLength: 36
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]+[a-zA-Z0-9]$
          readOnly: true
        operation:
          type: string
          description: Operation to perform on the input documents.
          default: Surrogate
          enum:
          - Redact
          - Surrogate
          - Tag
          x-ms-enum:
            name: DeidentificationOperationType
            modelAsString: true
            values:
            - name: Redact
              value: Redact
              description: Redact Operation will remove all entities of PHI and replace them with a placeholder value.
            - name: Surrogate
              value: Surrogate
              description: Surrogation Operation will replace all entities of PHI with a surrogate value.
            - name: Tag
              value: Tag
              description: Tag Operation will detect all entities of PHI, their type, and return their locations in the document.
        sourceLocation:
          $ref: '#/components/schemas/SourceStorageLocation'
          description: Storage location to perform the operation on.
        targetLocation:
          $ref: '#/components/schemas/TargetStorageLocation'
          description: Target location to store output of operation.
        customizations:
          $ref: '#/components/schemas/DeidentificationJobCustomizationOptions'
          description: Customization parameters to override default service behaviors.
        status:
          $ref: '#/components/schemas/Azure.Core.Foundations.OperationState'
          description: Current status of a job.
          readOnly: true
        error:
          $ref: '#/components/schemas/Azure.Core.Foundations.Error'
          description: Error when job fails in it's entirety.
          readOnly: true
        lastUpdatedAt:
          type: string
          format: date-time
          description: 'Date and time when the job was completed.


            If the job is canceled, this is the time when the job was canceled.


            If the job failed, this is the time when the job failed.'
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Date and time when the job was created.
          readOnly: true
        startedAt:
          type: string
          format: date-time
          description: Date and time when the job was started.
          readOnly: true
        summary:
          $ref: '#/components/schemas/DeidentificationJobSummary'
          description: Summary of a job. Exists only when the job is completed.
          readOnly: true
      required:
      - name
      - sourceLocation
      - targetLocation
      - status
      - lastUpdatedAt
      - createdAt
    PagedDeidentificationDocumentDetails:
      type: object
      description: Paged collection of DeidentificationDocumentDetails items
      properties:
        value:
          type: array
          description: The DeidentificationDocumentDetails items on this page
          items:
            $ref: '#/components/schemas/DeidentificationDocumentDetails'
        nextLink:
          type: string
          format: uri
          description: The link to the next page of items
      required:
      - value
    DeidentificationDocumentLocation:
      type: object
      description: Location of a document.
      properties:
        location:
          type: string
          format: uri
          description: Location of document in storage.
          maxLength: 1024
        etag:
          $ref: '#/components/schemas/Azure.Core.eTag'
          description: The entity tag for this resource.
          readOnly: true
      required:
      - location
      - etag
    DeidentificationJobSummary:
      type: object
      description: Summary metrics of a job.
      properties:
        successful:
          type: integer
          format: int32
          description: Number of documents that have completed.
        failed:
          type: integer
          format: int32
          description: Number of documents that have failed.
        canceled:
          type: integer
          format: int32
          description: Number of documents that have been canceled.
        total:
          type: integer
          format: int32
          description: Number of documents total.
        bytesProcessed:
          type: integer
          format: int64
          description: Number of bytes processed.
      required:
      - successful
      - failed
      - canceled
      - total
      - bytesProcessed
    TargetStorageLocation:
      type: object
      description: Storage location.
      properties:
        location:
          type: string
          format: uri
          description: URL to storage location.
        prefix:
          type: string
          description: 'Replaces the input prefix of a file path with the output prefix, preserving the rest of the path structure.


            Example:

            File full path: documents/user/note.txt

            Input Prefix: "documents/user/"

            Output Prefix: "output_docs/"


            Output file: "output_docs/note.txt"'
          maxLength: 1024
        overwrite:
          type: boolean
          description: When set to true during a job, the service will overwrite the output location if it already exists.
          default: false
      required:
      - location
      - prefix
    Azure.Core.Foundations.ErrorResponse:
      type: object
      description: A response containing error details.
      properties:
        error:
          $ref: '#/components/schemas/Azure.Core.Foundations.Error'
          description: The error object.
      required:
      - error
    Azure.Core.eTag:
      type: string
      description: 'The ETag (or entity tag) HTTP response header is an identifier for a specific version of a resource.

        It lets caches be more efficient and save bandwidth, as a web server does not need to resend a full response if the content was not changed.


        It is a string of ASCII characters placed between double quotes, like "675af34563dc-tr34".'
    SourceStorageLocation:
      type: object
      description: Storage location.
      properties:
        location:
          type: string
          format: uri
          description: URL to storage location.
        prefix:
          type: string
          description: Prefix to filter path by.
          maxLength: 1024
        extensions:
          type: array
          description: List of extensions to filter path by.
          default:
          - '*'
          minItems: 1
          items:
            type: string
      required:
      - location
      - prefix
    Azure.Core.Foundations.Error:
      type: object
      description: The error object.
      properties:
        code:
          type: string
          description: One of a server-defined set of error codes.
        message:
          type: string
          description: A human-readable representation of the error.
        target:
          type: string
          description: The target of the error.
        details:
          type: array
          description: An array of details about specific errors that led to this reported error.
          items:
            $ref: '#/components/schemas/Azure.Core.Foundations.Error'
        innererror:
          $ref: '#/components/schemas/Azure.Core.Foundations.InnerError'
          description: An object containing more specific information than the current object about the error.
      required:
      - code
      - message
    DeidentificationJobCustomizationOptions:
      type: object
      description: Customizations options to override default service behaviors for job usage.
      properties:
        redactionFormat:
          type: string
          description: "Format of the redacted output. Only valid when Operation is Redact. \nPlease refer to https://learn.microsoft.com/azure/healthcare-apis/deidentification/redaction-format for more details."
          minLength: 1
          maxLength: 16
        surrogateLocale:
          type: string
          description: Locale in which the output surrogates are written.
          default: en-US
    PagedDeidentificationJob:
      type: object
      description: Paged collection of DeidentificationJob items
      properties:
        value:
          type: array
          description: The DeidentificationJob items on this page
          items:
            $ref: '#/components/schemas/DeidentificationJob'
        nextLink:
          type: string
          format: uri
          description: The link to the next page of items
      required:
      - value
  parameters:
    Azure.Core.MaxPageSizeQueryParameter:
      name: maxpagesize
      in: query
      description: The maximum number of result items per page.
      required: false
      x-ms-parameter-location: method
      schema:
        type: integer
        format: int32
    PaginationByTokenQueryParameters.continuationToken:
      name: continuationToken
      in: query
      description: Token to continue a previous query.
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    Azure.Core.Foundations.ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      x-ms-parameter-location: method
      x-ms-client-name: apiVersion
      schema:
        type: string
        minLength: 1
    Azure.Core.ClientRequestIdHeader:
      name: x-ms-client-request-id
      in: header
      description: An opaque, globally-unique, client-generated string identifier for the request.
      required: false
      x-ms-parameter-location: method
      x-ms-client-name: clientRequestId
      schema:
        type: string
        format: uuid
  securitySchemes:
    AadToken:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            https://deid.azure.com/.default: ''
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/token
      description: The Azure Active Directory OAuth2 Flow
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: Url of your De-identification Service.
    required: true
    type: string
    format: uri
    x-ms-skip-url-encoding: true