swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Update Management API
schemes:
- https
tags:
- name: Update Management
paths:
  /deviceUpdate/{instanceId}/updates:
    get:
      tags:
      - Update Management
      description: Get a list of all updates that have been imported to Device Update for IoT Hub.
      operationId: microsoftAzureDeviceupdateListupdates
      x-ms-examples:
        DeviceUpdate_ListUpdates:
          $ref: ./examples/DeviceUpdate_ListUpdates.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - name: search
        in: query
        required: false
        type: string
        description: Request updates matching a free-text search expression.
      - name: filter
        in: query
        required: false
        type: string
        description: Filter updates by its properties.
      responses:
        '200':
          description: All imported updates, or empty list if there is none.
          schema:
            $ref: '#/definitions/UpdateList'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-odata: '#/definitions/UpdateFilter'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates
  /deviceUpdate/{instanceId}/updates:import:
    post:
      tags:
      - Update Management
      operationId: microsoftAzureDeviceupdateImportupdate
      x-ms-long-running-operation: true
      x-ms-examples:
        DeviceUpdate_ImportUpdate:
          $ref: ./examples/DeviceUpdate_ImportUpdate.json
      description: Import new update version. This is a long-running-operation; use Operation-Location response header value to check for operation status.
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - name: updateToImport
        in: body
        required: true
        schema:
          $ref: '#/definitions/ImportUpdateInput'
        description: The update to be imported.
      responses:
        '202':
          description: Accepted update import request; background operation location to track status is specified in Operation-Location response header.
          headers:
            Operation-Location:
              type: string
              description: Url to retrieve the import operation status.
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Post Deviceupdate Instanceid Updates:import
  /deviceUpdate/{instanceId}/updates/providers/{provider}/names/{name}/versions/{version}:
    get:
      tags:
      - Update Management
      description: Get a specific update version.
      operationId: microsoftAzureDeviceupdateGetupdate
      x-ms-examples:
        DeviceUpdate_GetUpdate:
          $ref: ./examples/DeviceUpdate_GetUpdate.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/UpdateProviderParameter'
      - $ref: '#/parameters/UpdateNameParameter'
      - $ref: '#/parameters/UpdateVersionParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - $ref: '#/parameters/IfNoneMatchParameter'
      responses:
        '200':
          description: The requested update version.
          schema:
            $ref: '#/definitions/Update'
        '304':
          description: Not modified.
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Providers Provider Names Name Versions Version
    delete:
      tags:
      - Update Management
      description: Delete a specific update version. This is a long-running-operation; use Operation-Location response header value to check for operation status.
      operationId: microsoftAzureDeviceupdateDeleteupdate
      x-ms-long-running-operation: true
      x-ms-examples:
        DeviceUpdate_DeleteUpdate:
          $ref: ./examples/DeviceUpdate_DeleteUpdate.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/UpdateProviderParameter'
      - $ref: '#/parameters/UpdateNameParameter'
      - $ref: '#/parameters/UpdateVersionParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '202':
          description: Accepted update deletion request; background operation location to track status is specified in Operation-Location response header.
          headers:
            Operation-Location:
              type: string
              description: Url to retrieve the operation status
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Delete Deviceupdate Instanceid Updates Providers Provider Names Name Versions Version
  /deviceUpdate/{instanceId}/updates/providers:
    get:
      tags:
      - Update Management
      description: Get a list of all update providers that have been imported to Device Update for IoT Hub.
      operationId: microsoftAzureDeviceupdateListproviders
      x-ms-examples:
        DeviceUpdate_ListProviders:
          $ref: ./examples/DeviceUpdate_ListProviders.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '200':
          description: All imported update providers, or empty list if there is none.
          schema:
            $ref: '#/definitions/StringsList'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Providers
  /deviceUpdate/{instanceId}/updates/providers/{provider}/names:
    get:
      tags:
      - Update Management
      description: Get a list of all update names that match the specified provider.
      operationId: microsoftAzureDeviceupdateListnames
      x-ms-examples:
        DeviceUpdate_ListNames:
          $ref: ./examples/DeviceUpdate_ListNames.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/UpdateProviderParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '200':
          description: All update names that match the specified provider, or empty list if there is none.
          schema:
            $ref: '#/definitions/StringsList'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Providers Provider Names
  /deviceUpdate/{instanceId}/updates/providers/{provider}/names/{name}/versions:
    get:
      tags:
      - Update Management
      description: Get a list of all update versions that match the specified provider and name.
      operationId: microsoftAzureDeviceupdateListversions
      x-ms-examples:
        DeviceUpdate_ListVersions:
          $ref: ./examples/DeviceUpdate_ListVersions.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/UpdateProviderParameter'
      - $ref: '#/parameters/UpdateNameParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - name: filter
        in: query
        required: false
        type: string
        description: Filter updates by its properties.
      responses:
        '200':
          description: All update versions that match the specified provider and name, or empty list if there is none.
          schema:
            $ref: '#/definitions/StringsList'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-odata: '#/definitions/UpdateFilter'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Providers Provider Names Name Versions
  /deviceUpdate/{instanceId}/updates/providers/{provider}/names/{name}/versions/{version}/files:
    get:
      tags:
      - Update Management
      description: Get a list of all update file identifiers for the specified version.
      operationId: microsoftAzureDeviceupdateListfiles
      x-ms-examples:
        DeviceUpdate_ListFiles:
          $ref: ./examples/DeviceUpdate_ListFiles.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/UpdateProviderParameter'
      - $ref: '#/parameters/UpdateNameParameter'
      - $ref: '#/parameters/UpdateVersionParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '200':
          description: All update file identifiers for the specified version.
          schema:
            $ref: '#/definitions/StringsList'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Providers Provider Names Name Versions Version Files
  /deviceUpdate/{instanceId}/updates/providers/{provider}/names/{name}/versions/{version}/files/{fileId}:
    get:
      tags:
      - Update Management
      description: Get a specific update file from the version.
      operationId: microsoftAzureDeviceupdateGetfile
      x-ms-examples:
        DeviceUpdate_GetFile:
          $ref: ./examples/DeviceUpdate_GetFile.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/UpdateProviderParameter'
      - $ref: '#/parameters/UpdateNameParameter'
      - $ref: '#/parameters/UpdateVersionParameter'
      - $ref: '#/parameters/FileIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - $ref: '#/parameters/IfNoneMatchParameter'
      responses:
        '200':
          description: The requested file entity.
          schema:
            $ref: '#/definitions/UpdateFile'
        '304':
          description: Not modified.
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Providers Provider Names Name Versions Version Files Fileid
  /deviceUpdate/{instanceId}/updates/operations:
    get:
      tags:
      - Update Management
      operationId: microsoftAzureDeviceupdateListoperations
      description: Get a list of all import update operations. Completed operations are kept for 7 days before auto-deleted. Delete operations are not returned by this API version.
      x-ms-examples:
        DeviceUpdate_ListOperations:
          $ref: ./examples/DeviceUpdate_ListOperations.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - name: filter
        in: query
        required: false
        type: string
        description: 'Restricts the set of operations returned. Only one specific filter is supported: "status eq ''NotStarted'' or status eq ''Running''"'
      - name: top
        in: query
        required: false
        type: integer
        format: int32
        description: Specifies a non-negative integer n that limits the number of items returned from a collection. The service returns the number of available items up to but not greater than the specified value n.
      - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Operation details.
          schema:
            $ref: '#/definitions/UpdateOperationsList'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-odata: '#/definitions/OperationFilter'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Operations
  /deviceUpdate/{instanceId}/updates/operations/{operationId}:
    get:
      tags:
      - Update Management
      operationId: microsoftAzureDeviceupdateGetoperation
      description: Retrieve operation status.
      x-ms-examples:
        DeviceUpdate_GetOperation:
          $ref: ./examples/DeviceUpdate_GetOperation.json
      parameters:
      - $ref: '#/parameters/InstanceIdParameter'
      - $ref: '#/parameters/OperationIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - $ref: '#/parameters/IfNoneMatchParameter'
      responses:
        '200':
          description: Operation status.
          headers:
            Retry-After:
              type: string
              description: Number of seconds to wait before checking the operation status again.
          schema:
            $ref: '#/definitions/UpdateOperation'
        '304':
          description: Not modified.
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Deviceupdate Instanceid Updates Operations Operationid
definitions:
  StringsList:
    description: The list of strings with server paging support.
    type: object
    properties:
      value:
        description: The collection of pageable items.
        type: array
        items:
          type: string
      nextLink:
        description: The link to the next page of items.
        type: string
    required:
    - value
  OperationStatus:
    type: string
    enum:
    - NotStarted
    - Running
    - Succeeded
    - Failed
    x-ms-enum:
      name: OperationStatus
      modelAsString: true
      values:
      - value: NotStarted
        name: NotStarted
        description: Background operation created but not started yet.
      - value: Running
        name: Running
        description: Background operation is currently running.
      - value: Succeeded
        name: Succeeded
        description: Background operation finished with success.
      - value: Failed
        name: Failed
        description: Background operation finished with failure.
    description: Operation status.
  UpdateFileBase:
    type: object
    properties:
      fileName:
        type: string
        description: File name.
      sizeInBytes:
        type: integer
        description: File size in number of bytes.
        format: int64
      hashes:
        type: object
        additionalProperties:
          type: string
          minItems: 1
        description: Mapping of hashing algorithm to base64 encoded hash values.
      mimeType:
        type: string
        description: File MIME type.
      scanResult:
        type: string
        description: Anti-malware scan result.
      scanDetails:
        type: string
        description: Anti-malware scan details.
      properties:
        type: object
        additionalProperties:
          type: string
          minItems: 0
        description: Optional file properties (not consumed by service but pass-through to device).
    required:
    - fileName
    - sizeInBytes
    - hashes
    description: Update file basic metadata.
  UpdateId:
    type: object
    properties:
      provider:
        type: string
        description: Update provider.
      name:
        type: string
        description: Update name.
      version:
        type: string
        description: Update version.
    required:
    - provider
    - name
    - version
    description: Update identifier.
  ImportUpdateInput:
    type: array
    items:
      $ref: '#/definitions/ImportUpdateInputItem'
    minItems: 1
    maxItems: 11
    description: Import update input metadata.
  UpdateInfo:
    type: object
    properties:
      updateId:
        $ref: '#/definitions/UpdateId'
        description: Update identifier.
      description:
        type: string
        description: Update description.
        readOnly: true
      friendlyName:
        type: string
        description: Friendly update name.
        readOnly: true
    required:
    - updateId
    description: Update information.
  UpdateFile:
    type: object
    allOf:
    - $ref: '#/definitions/UpdateFileBase'
    properties:
      fileId:
        type: string
        description: File identity, generated by server at import time.
      relatedFiles:
        type: array
        items:
          $ref: '#/definitions/UpdateFileBase'
        description: Optional related files metadata used together DownloadHandler metadata to download payload file.
      downloadHandler:
        $ref: '#/definitions/UpdateFileDownloadHandler'
        description: Optional download handler for utilizing related files to download payload file.
      etag:
        type: string
        description: File ETag.
    required:
    - fileId
    description: Update file metadata.
  FileImportMetadata:
    type: object
    properties:
      filename:
        type: string
        description: Update file name as specified inside import manifest.
      url:
        type: string
        description: Azure Blob location from which the update file can be downloaded by Device Update for IoT Hub. This is typically a read-only SAS-protected blob URL with an expiration set to at least 4 hours.
    required:
    - filename
    - url
    description: Metadata describing an update file.
  ImportManifestMetadata:
    type: object
    properties:
      url:
        type: string
        description: Azure Blob location from which the import manifest can be downloaded by Device Update for IoT Hub. This is typically a read-only SAS-protected blob URL with an expiration set to at least 4 hours.
      sizeInBytes:
        type: integer
        description: File size in number of bytes.
        format: int64
      hashes:
        type: object
        additionalProperties:
          type: string
          minItems: 1
        description: A JSON object containing the hash(es) of the file. At least SHA256 hash is required. This object can be thought of as a set of key-value pairs where the key is the hash algorithm, and the value is the hash of the file calculated using that algorithm.
    required:
    - url
    - sizeInBytes
    - hashes
    description: Metadata describing the import manifest, a document which describes the files and other metadata about an update version.
  UpdateList:
    description: The list of updates.
    type: object
    properties:
      value:
        description: The collection of pageable items.
        type: array
        items:
          $ref: '#/definitions/Update'
      nextLink:
        description: The link to the next page of items.
        type: string
    required:
    - value
  Error:
    type: object
    properties:
      code:
        type: string
        description: Server defined error code.
      message:
        type: string
        description: A human-readable representation of the error.
      target:
        type: string
        description: The target of the error.
      details:
        type: array
        items:
          $ref: '#/definitions/Error'
        description: An array of errors that led to the reported error.
      innererror:
        $ref: '#/definitions/InnerError'
        description: An object containing more specific information than the current object about the error.
      occurredDateTime:
        type: string
        description: Date and time in UTC when the error occurred.
        format: date-time
    required:
    - code
    - message
    description: Error details.
  Compatibility:
    type: object
    additionalProperties:
      type: string
      minItems: 1
      maxItems: 5
    description: Key-value pairs representing update compatibility information.
  Update:
    type: object
    properties:
      updateId:
        $ref: '#/definitions/UpdateId'
        description: Update identity.
      description:
        type: string
        description: Update description specified by creator.
        minLength: 1
        maxLength: 512
      friendlyName:
        type: string
        description: Friendly update name specified by importer.
        minLength: 1
        maxLength: 512
      isDeployable:
        type: boolean
        description: Whether the update can be deployed to a device on its own.
        default: true
      updateType:
        type: string
        description: Update type. Deprecated in latest import manifest schema.
      installedCriteria:
        type: string
        description: String interpreted by Device Update client to determine if the update is installed on the device. Deprecated in latest import manifest schema.
      compatibility:
        type: array
        items:
          $ref: '#/definitions/Compatibility'
        minItems: 1
        maxItems: 10
        description: List of update compatibility information.
      instructions:
        $ref: '#/definitions/Instructions'
        description: Update install instructions.
      referencedBy:
        type: array
        items:
          $ref: '#/definitions/UpdateId'
        minItems: 1
        description: List of update identities that reference this update.
      scanResult:
        type: string
        description: Update aggregate scan result (calculated from payload file scan results).
      manifestVersion:
        type: string
        description: Schema version of manifest used to import the update.
      importedDateTime:
        type: string
        description: Date and time in UTC when the update was imported.
        format: date-time
      createdDateTime:
        type: string
        format: date-time
        description: Date and time in UTC when the update was created.
      etag:
        type: string
        description: Update ETag.
    required:
    - updateId
    - compatibility
    - manifestVersion
    - importedDateTime
    - createdDateTime
    description: Update metadata.
  UpdateOperation:
    type: object
    properties:
      operationId:
        type: string
        description: Operation Id.
      status:
        $ref: '#/definitions/OperationStatus'
        description: Operation status.
      update:
        $ref: '#/definitions/UpdateInfo'
        description: The update being imported or deleted. For import, this property will only be populated after import manifest is processed successfully.
      resourceLocation:
        type: string
        description: Location of the imported update when operation is successful.
      error:
        $ref: '#/definitions/Error'
        description: Operation error encountered, if any.
      traceId:
        type: string
        description: Operation correlation identity that can used by Microsoft Support for troubleshooting.
      lastActionDateTime:
        type: string
        format: date-time
        description: Date and time in UTC when the operation status was last updated.
      createdDateTime:
        type: string
        format: date-time
        description: Date and time in UTC when the operation was created.
      etag:
        type: string
        description: Operation ETag.
    required:
    - operationId
    - status
    - lastActionDateTime
    - createdDateTime
    description: Operation metadata.
  ImportUpdateInputItem:
    type: object
    properties:
      importManifest:
        $ref: '#/definitions/ImportManifestMetadata'
        description: Import manifest metadata like source URL, file size/hashes, etc.
      friendlyName:
        type: string
        minLength: 1
        maxLength: 512
        description: Friendly update name.
      files:
        type: array
        items:
          $ref: '#/definitions/FileImportMetadata'
        minItems: 1
        maxItems: 5
        description: One or more update file properties like filename and source URL.
    required:
    - importManifest
    description: Import update input item metadata.
  UpdateOperationsList:
    description: The list of operations with server paging support.
    type: object
    properties:
      value:
        description: The collection of pageable items.
        type: array
        items:
          $ref: '#/definitions/UpdateOperation'
      nextLink:
        description: The link to the next page of items.
        type: string
    required:
    - value
  ErrorResponse:
    description: Common error response.
    type: object
    properties:
      error:
        $ref: '#/definitions/Error'
        description: The error details.
    required:
    - error
  UpdateFileDownloadHandler:
    type: object
    properties:
      id:
        type: string
        description: Download handler identifier.
    required:
    - id
    description: Download handler for utilizing related files to download payload file.
  Instructions:
    type: object
    properties:
      steps:
        description: Collection of installation steps.
        type: array
        items:
          $ref: '#/definitions/Step'
        minItems: 1
        maxItems: 10
    required:
    - steps
  InnerError:
    type: object
    properties:
      code:
        type: string
        description: A more specific error code than what was provided by the containing error.
      message:
        type: string
        description: A human-readable representation of the error.
      errorDetail:
        type: string
        description: The internal error or exception message.
      innerError:
        $ref: '#/definitions/InnerError'
        description: An object containing more specific information than the current object about the error.
    required:
    - code
    description: An object containing more specific information than the current object about the error.
  Step:
    description: Update install instruction step.
    type: object
    properties:
      type:
        description: Step type.
        type: string
        enum:
        - inline
        - reference
        default: inline
        x-ms-enum:
          name: StepType
          modelAsString: true
          values:
          - value: Inline
            name: Inline
            description: Step type that performs code execution.
          - value: Reference
            name: Reference
            description: Step type that installs another update.
      description:
        description: Step description.
        type: string
        minLength: 1
        maxLength: 64
      handler:
        description: Identity of handler that will execute this step. Required if step type is inline.
        type: string
        minLength: 1
        maxLength: 32
      handlerProperties:
        description: Parameters to be passed to handler during execution.
        type: object
      files:
        description: Collection of file names to be passed to handler during execution. Required if step type is inline.
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 5
      updateId:
        description: Referenced child update identity.  Required if step type is reference.
        $ref: '#/definitions/UpdateId'
    minProperties: 2
parameters:
  ApiVersionParameter:
    name: api-version
    in: query
    required: true
    type: string
    description: Version of the API to be used with the client request.
  UpdateProviderParameter:
    name: provider
    in: path
    required: true
    type: string
    description: Update provider.
    x-ms-parameter-location: method
  OperationIdParameter:
    name: operationId
    in: path
    description: Operation identifier.
    minLength: 1
    maxLength: 256
    required: true
    type: string
    x-ms-parameter-location: method
  FileIdParameter:
    name: fileId
    in: path
    required: true
    type: string
    description: File identifier.
    x-ms-parameter-location: method
  IfNoneMatchParameter:
    name: If-None-Match
    in: header
    required: false
    description: Defines the If-None-Match condition. The operation will be performed only if the ETag on the server does not match this value.
    type: string
    x-ms-parameter-grouping:
      name: access-condition
    x-ms-parameter-location: method
  InstanceIdParameter:
    name: instanceId
    in: path
    required: true
    type: string
    x-ms-skip-url-encoding: true
    description: Account instance identifier.
    x-ms-parameter-location: client
    x-ms-parameter-grouping:
      name: account-options
  UpdateNameParameter:
    name: name
    in: path
    required: true
    type: string
    description: Update name.
    x-ms-parameter-location: method
  UpdateVersionParameter:
    name: version
    in: path
    required: true
    type: string
    description: Update version.
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'