Microsoft Azure Execution API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Execution API
tags:
- name: Execution
paths:
  ? /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/startlocalrun
  : post:
      tags:
      - Execution
      summary: Microsoft Azure Start A Run On A Local Machine
      description: Starts an experiment run using the provided definition.json file to define the run.<br>            The source code and configuration is defined in a zip archive in project.zip.
      operationId: microsoftAzureRunsStartlocalrun
      parameters:
      - $ref: '#/components/parameters/subscriptionIdParameter'
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        schema:
          type: string
      - name: runId
        in: query
        description: A run id. If not supplied a run id will be created automatically.
        required: false
        schema:
          type: string
          pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: File Response
          content:
            application/json:
              schema:
                format: binary
                type: string
            application/octet-stream:
              schema:
                format: binary
                type: string
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Start a local run:
          $ref: ./examples/startLocalRun.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunDefinition'
        description: A JSON run definition structure.
        required: true
  ? /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/startrun
  : post:
      tags:
      - Execution
      summary: Microsoft Azure Start A Run On A Remote Compute Target
      description: Starts an experiment run using the provided definition.json file to define the run.<br>            The source code and configuration is defined in a zip archive in project.zip.
      operationId: microsoftAzureRunsStartrun
      parameters:
      - $ref: '#/components/parameters/subscriptionIdParameter'
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        schema:
          type: string
      - name: runId
        in: query
        description: A run id. If not supplied a run id will be created automatically.
        required: false
        schema:
          type: string
          pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: A run was successfully started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartRunResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Start a run:
          $ref: ./examples/startRun.json
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                runDefinitionFile:
                  type: string
                  description: The JSON file containing the RunDefinition
                  format: binary
                projectZipFile:
                  type: string
                  description: The zip archive of the project folder containing the source code to use for the run.
                  format: binary
              required:
              - runDefinitionFile
              - projectZipFile
  ? /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/snapshotrun
  : post:
      tags:
      - Execution
      summary: Microsoft Azure Start A Run From A Snapshot On A Remote Compute Target
      description: Starts an experiment run on the remote compute target using the provided definition.json file to define the run.<br>            The code for the run is retrieved using the snapshotId in definition.json.
      operationId: microsoftAzureRunsStartsnapshotrun
      parameters:
      - $ref: '#/components/parameters/subscriptionIdParameter'
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        schema:
          type: string
      - name: runId
        in: query
        description: A run id. If not supplied a run id will be created automatically.
        required: false
        schema:
          type: string
          pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: A snapshot run was successfully started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartRunResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Start a snapshot run:
          $ref: ./examples/startSnapshotRun.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunDefinition'
        description: A JSON run definition structure.
        required: true
  ? /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/runId/{runId}/cancel
  : post:
      tags:
      - Execution
      summary: Microsoft Azure Cancel A Run
      description: Cancels a run within an experiment.
      operationId: microsoftAzureRunsCancelrunwithuri
      parameters:
      - $ref: '#/components/parameters/subscriptionIdParameter'
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        schema:
          type: string
      - name: runId
        in: path
        description: The id of the run to cancel.
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: The run was successfully cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartRunResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Cancel a run with URI:
          $ref: ./examples/cancelRunWithUri.json
components:
  schemas:
    StartRunResult:
      description: Contains the details of a run.
      required:
      - runId
      type: object
      properties:
        runId:
          description: The identifier for a run.
          type: string
          example: myexperiment_155000000001_0
    EnvironmentDefinition:
      type: object
      properties:
        name:
          description: The name of the environment.
          type: string
          example: mydevenvironment
        version:
          description: The environment version.
          type: string
          example: '1'
        python:
          $ref: '#/components/schemas/PythonSection'
          description: Settings for a Python environment.
        environmentVariables:
          description: Definition of environment variables to be defined in the environment.
          type: object
          additionalProperties:
            type: string
        docker:
          $ref: '#/components/schemas/DockerSection'
          description: The definition of a Docker container.
        spark:
          $ref: '#/components/schemas/SparkSection'
          description: The configuration for a Spark environment.
        inferencingStackVersion:
          description: 'The inferencing stack version added to the image. To avoid adding an inferencing stack, do not set this value. Valid values: "latest".'
          type: string
          example: latest
    InnerErrorResponse:
      description: A nested structure of errors.
      type: object
      properties:
        code:
          description: The error code.
          type: string
        innerError:
          $ref: '#/components/schemas/InnerErrorResponse'
          description: A nested list of inner errors. When evaluating errors, clients MUST traverse through all of the nested “innerErrors” and choose the deepest one that they understand.
    TensorflowConfiguration:
      type: object
      properties:
        workerCount:
          format: int32
          description: The number of workers.
          type: integer
          example: '2'
        parameterServerCount:
          format: int32
          description: Number of parameter servers.
          type: integer
          example: '1'
    SparkConfiguration:
      type: object
      properties:
        configuration:
          type: object
          additionalProperties:
            type: string
    RunConfiguration:
      type: object
      properties:
        script:
          description: The relative path to the python script file. The file path is relative to the source_directory passed to submit run.
          type: string
          example: findsquare.py
        arguments:
          description: Command line arguments for the python script file.
          uniqueItems: false
          type: array
          items:
            type: string
          example: '["234"]'
        framework:
          description: The supported frameworks are Python, PySpark, CNTK, TensorFlow, and PyTorch. Use Tensorflow for AmlCompute clusters, and Python for distributed training jobs.
          enum:
          - Python
          - PySpark
          - Cntk
          - TensorFlow
          - PyTorch
          type: string
          example: Python
          x-ms-enum:
            name: Framework
            modelAsString: false
        communicator:
          description: 'The supported communicators are None, ParameterServer, OpenMpi, and IntelMpi Keep in mind that OpenMpi requires a custom image with OpenMpi installed.

            Use ParameterServer or OpenMpi for AmlCompute clusters. Use IntelMpi for distributed training jobs.'
          enum:
          - None
          - ParameterServer
          - Gloo
          - Mpi
          - Nccl
          type: string
          example: None
          x-ms-enum:
            name: Communicator
            modelAsString: false
        target:
          description: Target refers to compute where the job is scheduled for execution. The default target is "local" referring to the local machine.
          type: string
          example: amlcompute
        dataReferences:
          description: All the data sources are made available to the run during execution based on each configuration.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DataReferenceConfiguration'
        jobName:
          description: 'This is primarily intended for notebooks to override the default job name.

            Defaults to ArgumentVector[0] if not specified.'
          type: string
          example: FindSquaresJob
        maxRunDurationSeconds:
          format: int64
          description: 'Maximum allowed time for the run. The system will attempt to automatically cancel the run if it took longer than this value.

            MaxRunDurationSeconds=null means infinite duration.'
          type: integer
          example: '84000'
        nodeCount:
          format: int32
          description: Number of compute nodes to run the job on. Only applies to AMLCompute.
          type: integer
          example: '1'
        environment:
          $ref: '#/components/schemas/EnvironmentDefinition'
          description: 'The environment definition, This field configures the python environment.

            It can be configured to use an existing Python environment or configured to setup a temp environment for the experiment.

            The definition is also responsible for setting the required application dependencies.'
        history:
          $ref: '#/components/schemas/HistoryConfiguration'
          description: This section is used to disable and enable experiment history logging features.
        spark:
          $ref: '#/components/schemas/SparkConfiguration'
          description: When the platform is set to Pyspark, The spark configuration is used to set the default sparkconf for the submitted job.
        tensorflow:
          $ref: '#/components/schemas/TensorflowConfiguration'
          description: 'The attribute is used to configure the distributed tensorflow parameters.

            This attribute takes effect only when the framework is set to TensorFlow, and the communicator to ParameterServer.

            AmlCompute is the only supported compute for this configuration.'
        mpi:
          $ref: '#/components/schemas/MpiConfiguration'
          description: 'The attribute is used to configure the distributed MPI job parameters.

            This attribute takes effect only when the framework is set to Python, and the communicator to OpenMpi or IntelMpi.

            AmlCompute is the only supported compute type for this configuration.'
        hdi:
          $ref: '#/components/schemas/HdiConfiguration'
          description: 'This attribute takes effect only when the target is set to an Azure HDI compute.

            The HDI Configuration is used to set the YARN deployment mode. It is defaulted to cluster mode.'
    MpiConfiguration:
      type: object
      properties:
        processCountPerNode:
          format: int32
          description: Number of processes per node.
          type: integer
          example: '2'
    ContainerRegistry:
      type: object
      properties:
        address:
          type: string
        username:
          type: string
        password:
          type: string
    DockerSection:
      type: object
      properties:
        baseImage:
          description: Base image used for Docker-based runs. Mutually exclusive with BaseDockerfile.
          type: string
          example: ubuntu:latest
        baseDockerfile:
          description: Base Dockerfile used for Docker-based runs. Mutually exclusive with BaseImage.
          type: string
          example: 'FROM ubuntu:latest

            RUN echo "Hello world!"'
        enabled:
          description: Set true to perform this run inside a Docker container.
          type: boolean
        sharedVolumes:
          description: Set false to disable AzureML's usage of the Docker shared volumes feature to work around bugs in certain versions of Docker for Windows.
          type: boolean
        arguments:
          description: Extra arguments to the Docker run command.
          uniqueItems: false
          type: array
          items:
            type: string
        baseImageRegistry:
          $ref: '#/components/schemas/ContainerRegistry'
          description: Image registry that contains the base image.
    HistoryConfiguration:
      type: object
      properties:
        outputCollection:
          description: Set to true to collect outputs and store in run history.
          type: boolean
        directoriesToWatch:
          description: The list of directories to monitor and upload files from.
          uniqueItems: false
          type: array
          items:
            type: string
          example: '["logs", "outputs"]'
    ErrorDetails:
      description: The error details.
      type: object
      properties:
        code:
          description: The error code.
          type: string
        message:
          description: The error message.
          type: string
        target:
          description: The target of the error (e.g., the name of the property in error).
          type: string
    RunDefinition:
      type: object
      properties:
        configuration:
          $ref: '#/components/schemas/RunConfiguration'
          description: 'Fully specified configuration information for the run. Even when that information

            is contained in configuration files within the project folder, the client collapses

            it all and inlines it into the run definition when submitting a run.'
        snapshotId:
          format: uuid
          description: 'Snapshots are user project folders that have been uploaded to the cloud for subsequent

            execution. This field is required when executing against cloud-based compute targets

            unless the run submission was against the API endpoint that takes a zipped project folder

            inline with the request.'
          type: string
        parentRunId:
          description: 'Specifies that the run history entry for this execution should be scoped within

            an existing run as a child. Defaults to null, meaning the run has no parent.

            This is intended for first-party service integration, not third-party API users.'
          type: string
          example: myexperiment_155000000001_0
        runType:
          description: Specifies the runsource property for this run. The default value is "experiment" if not specified.
          type: string
          example: experiment
    SparkMavenPackage:
      type: object
      properties:
        group:
          type: string
        artifact:
          type: string
        version:
          type: string
    ErrorResponse:
      description: The error response.
      type: object
      properties:
        error:
          $ref: '#/components/schemas/RootError'
          description: The top level error that occurred.
        correlation:
          description: Dictionary containing correlation details for the error.
          type: object
          additionalProperties:
            type: string
        environment:
          description: The hosting environment.
          type: string
        location:
          description: The Azure region.
          type: string
        time:
          format: date-time
          description: The time in UTC.
          type: string
    PythonSection:
      type: object
      properties:
        interpreterPath:
          description: The python interpreter path. This is only used when user_managed_dependencies=True.
          type: string
        userManagedDependencies:
          description: True means that AzureML reuses an existing python environment; False means that AzureML will create a python environment based on the Conda dependencies specification.
          type: boolean
        condaDependencies:
          type: object
        baseCondaEnvironment:
          type: string
    SparkSection:
      type: object
      properties:
        repositories:
          description: The list of spark repositories.
          uniqueItems: false
          type: array
          items:
            type: string
        packages:
          description: The Spark packages to use.
          uniqueItems: false
          type: array
          items:
            $ref: '#/components/schemas/SparkMavenPackage'
        precachePackages:
          description: Whether to precache the packages.
          type: boolean
    DataReferenceConfiguration:
      description: A class for managing DataReferenceConfiguration.
      type: object
      properties:
        dataStoreName:
          description: The name of the data store.
          type: string
          example: myblobstore
        mode:
          description: Operation on the datastore, mount, download, upload.
          enum:
          - Mount
          - Download
          - Upload
          type: string
          example: Mount
          x-ms-enum:
            name: DataStoreMode
            modelAsString: false
        pathOnDataStore:
          description: Relative path on the datastore.
          type: string
          example: /images/validation
        pathOnCompute:
          description: The path on the compute target.
          type: string
        overwrite:
          description: Whether to overwrite the data if existing.
          type: boolean
    RootError:
      description: The root error.
      type: object
      properties:
        code:
          description: 'The service-defined error code. Supported error codes: ServiceError, UserError, ValidationError, AzureStorageError, TransientError, RequestThrottled.'
          type: string
        message:
          description: A human-readable representation of the error.
          type: string
        target:
          description: The target of the error (e.g., the name of the property in error).
          type: string
        details:
          description: The related errors that occurred during the request.
          uniqueItems: false
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
        innerError:
          $ref: '#/components/schemas/InnerErrorResponse'
          description: A nested list of inner errors. When evaluating errors, clients MUST traverse through all of the nested “innerErrors” and choose the deepest one that they understand.
    HdiConfiguration:
      type: object
      properties:
        yarnDeployMode:
          enum:
          - None
          - Client
          - Cluster
          type: string
          x-ms-enum:
            name: YarnDeployMode
            modelAsString: false
  parameters:
    resourceGroupNameParameter:
      name: resourceGroupName
      in: path
      description: The Name of the resource group in which the workspace is located.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    workspaceNameParameter:
      name: workspaceName
      in: path
      description: The name of the workspace.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    subscriptionIdParameter:
      name: subscriptionId
      in: path
      description: The Azure Subscription ID.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
        format: uuid
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'