Microsoft Azure Execution API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Execution API
schemes:
- https
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
      consumes:
      - application/json
      produces:
      - application/json
      - application/octet-stream
      parameters:
      - $ref: '#/parameters/subscriptionIdParameter'
      - $ref: '#/parameters/resourceGroupNameParameter'
      - $ref: '#/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        type: string
      - name: definition
        in: body
        description: A JSON run definition structure.
        required: true
        schema:
          $ref: '#/definitions/RunDefinition'
      - name: runId
        in: query
        description: A run id. If not supplied a run id will be created automatically.
        required: false
        type: string
        pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: File Response
          schema:
            format: byte
            type: file
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Start a local run:
          $ref: ./examples/startLocalRun.json
  ? /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
      consumes:
      - multipart/form-data
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/subscriptionIdParameter'
      - $ref: '#/parameters/resourceGroupNameParameter'
      - $ref: '#/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        type: string
      - name: runDefinitionFile
        in: formData
        description: The JSON file containing the RunDefinition
        required: true
        type: file
      - name: projectZipFile
        in: formData
        description: The zip archive of the project folder containing the source code to use for the run.
        required: true
        type: file
      - name: runId
        in: query
        description: A run id. If not supplied a run id will be created automatically.
        required: false
        type: string
        pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: A run was successfully started.
          schema:
            $ref: '#/definitions/StartRunResult'
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Start a run:
          $ref: ./examples/startRun.json
  ? /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
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/subscriptionIdParameter'
      - $ref: '#/parameters/resourceGroupNameParameter'
      - $ref: '#/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        type: string
      - name: definition
        in: body
        description: A JSON run definition structure.
        required: true
        schema:
          $ref: '#/definitions/RunDefinition'
      - name: runId
        in: query
        description: A run id. If not supplied a run id will be created automatically.
        required: false
        type: string
        pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: A snapshot run was successfully started.
          schema:
            $ref: '#/definitions/StartRunResult'
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Start a snapshot run:
          $ref: ./examples/startSnapshotRun.json
  ? /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
      consumes: []
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/subscriptionIdParameter'
      - $ref: '#/parameters/resourceGroupNameParameter'
      - $ref: '#/parameters/workspaceNameParameter'
      - name: experimentName
        in: path
        description: The experiment name.
        required: true
        type: string
      - name: runId
        in: path
        description: The id of the run to cancel.
        required: true
        type: string
        pattern: ^[a-zA-Z0-9][\w-]{0,255}$
      responses:
        '200':
          description: The run was successfully cancelled.
          schema:
            $ref: '#/definitions/StartRunResult'
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Cancel a run with URI:
          $ref: ./examples/cancelRunWithUri.json
definitions:
  RunDefinition:
    type: object
    properties:
      configuration:
        $ref: '#/definitions/RunConfiguration'
        description: "Fully specified configuration information for the run. Even when that information\r\nis contained in configuration files within the project folder, the client collapses\r\nit 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\r\nexecution. This field is required when executing against cloud-based compute targets\r\nunless the run submission was against the API endpoint that takes a zipped project folder\r\ninline with the request."
        type: string
      parentRunId:
        description: "Specifies that the run history entry for this execution should be scoped within\r\nan existing run as a child. Defaults to null, meaning the run has no parent.\r\nThis 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
  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
  SparkConfiguration:
    type: object
    properties:
      configuration:
        type: object
        additionalProperties:
          type: string
  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: '#/definitions/ErrorDetails'
      innerError:
        $ref: '#/definitions/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.
  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: '#/definitions/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
  MpiConfiguration:
    type: object
    properties:
      processCountPerNode:
        format: int32
        description: Number of processes per node.
        type: integer
        example: '2'
  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
  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\r\nRUN 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: '#/definitions/ContainerRegistry'
        description: Image registry that contains the base image.
  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.\r\nUse 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: '#/definitions/DataReferenceConfiguration'
      jobName:
        description: "This is primarily intended for notebooks to override the default job name.\r\nDefaults 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.\r\nMaxRunDurationSeconds=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: '#/definitions/EnvironmentDefinition'
        description: "The environment definition, This field configures the python environment.\r\nIt can be configured to use an existing Python environment or configured to setup a temp environment for the experiment.\r\nThe definition is also responsible for setting the required application dependencies."
      history:
        $ref: '#/definitions/HistoryConfiguration'
        description: This section is used to disable and enable experiment history logging features.
      spark:
        $ref: '#/definitions/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: '#/definitions/TensorflowConfiguration'
        description: "The attribute is used to configure the distributed tensorflow parameters.\r\nThis attribute takes effect only when the framework is set to TensorFlow, and the communicator to ParameterServer.\r\nAmlCompute is the only supported compute for this configuration."
      mpi:
        $ref: '#/definitions/MpiConfiguration'
        description: "The attribute is used to configure the distributed MPI job parameters.\r\nThis attribute takes effect only when the framework is set to Python, and the communicator to OpenMpi or IntelMpi.\r\nAmlCompute is the only supported compute type for this configuration."
      hdi:
        $ref: '#/definitions/HdiConfiguration'
        description: "This attribute takes effect only when the target is set to an Azure HDI compute.\r\nThe HDI Configuration is used to set the YARN deployment mode. It is defaulted to cluster mode."
  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: '#/definitions/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: '#/definitions/DockerSection'
        description: The definition of a Docker container.
      spark:
        $ref: '#/definitions/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
  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
  HdiConfiguration:
    type: object
    properties:
      yarnDeployMode:
        enum:
        - None
        - Client
        - Cluster
        type: string
        x-ms-enum:
          name: YarnDeployMode
          modelAsString: false
  ErrorResponse:
    description: The error response.
    type: object
    properties:
      error:
        $ref: '#/definitions/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
  SparkMavenPackage:
    type: object
    properties:
      group:
        type: string
      artifact:
        type: string
      version:
        type: string
  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"]'
  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'
  InnerErrorResponse:
    description: A nested structure of errors.
    type: object
    properties:
      code:
        description: The error code.
        type: string
      innerError:
        $ref: '#/definitions/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.
parameters:
  resourceGroupNameParameter:
    name: resourceGroupName
    in: path
    description: The Name of the resource group in which the workspace is located.
    required: true
    type: string
    x-ms-parameter-location: method
  workspaceNameParameter:
    name: workspaceName
    in: path
    description: The name of the workspace.
    required: true
    type: string
    x-ms-parameter-location: method
  subscriptionIdParameter:
    name: subscriptionId
    in: path
    description: The Azure Subscription ID.
    required: true
    type: string
    format: uuid
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'