Getting Download Task Status

The get-download-status operation is used to retrieve the status of an application package download task.

The following statuses are possible:

  • "finished/error" - the task did not start because the package is not found in the APS Catalog
  • "finished/package-id" - the task is successfully completed
  • "in-progress/current" - package download task is currently in progress
  • "in-progress" lacking the "current" child node - package download task is not yet started but queued

In this chapter:

Request Packet Structure

Response Packet Structure

Samples

 

Request Packet Structure

A request XML package that retrieves the status of an application package download task should include the get-download-status operation node:

<packet version="1.6.2.0">
<aps>
   <get-download-status>
...
   </get-download-status>
</aps>
</packet>

The get-download-status node is structured as follows:

APSPackageDownloadStatusInputType

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.

  • filter, required

    Filters download tasks which status should be retrieved. Data type: none.

    If it is defined with empty value, than a list of all download tasks within the current download transaction is returned. On Windows, a separate transaction is created for each download task. Download transaction lasts as soon as lasts the download process.

  • task-id, optional

    Specifies the ID of download task (returned as a result of the <download-package> operation). Data type: id_type (common.xsd).

 

Response Packet Structure

The get-download-status node of the output XML packet is structured as follows:

APSPackageDownloadStatusOutputType

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.

  • result, required

    Wraps the response retrieved from the server. Data type: resultType (common.xsd).

  • status, required

    Specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

  • errcode, required if the operation fails

    Returns the error code. Data type: integer.

  • errtext, required if the request contained non-empty filter

    Returns the error message. Data type: string.

  • filter-id, required if the operation succeeds

    Returns the ID by which the operation was filtered. Data type: any.

  • id, required if the operation succeeds

    Returns the ID of the download task whose status is retrieved. Data type: id_type (common.xsd)

  • task, optional

    Holds a collection of data describing the download task status. Data type: none.

    Structured as follows:

APSPackageDownloadStatusOutputType-task.gif

  • id, required

    Returns the ID of the download task whose status is retrieved. Data type: id_type (common.xsd).

  • finished, optional

    Specifies that the download task is finished. Data type: none.

  • in-progress, optional

    Specifies that the download task is in progress, or is placed in the download queue in case several packages are specified for download at a time. Data type: APSPackageDownloadStatusInProgress (aps.xsd).

  • error, optional

    Specifies that the download was finished with error. Contains error description. Data type: none.

  • package-id, required if the package download completed successfully

    Specifies that the download was finished successfully and returns the ID assigned to the package on your server. Data type: id_type (common.xsd).

  • total, required

    Specifies the total application size in bytes. Data type: integer.

  • completed, required

    Specifies the size of the downloaded part, also in bytes. Data type: integer.

  • current, optional

    Specifies that the download task is currently in progress, opposed to the tasks awaiting at the download queue. Data type: string.

 

Samples

Getting status of a particular download task

This packet requests status of download task with ID 18:

<packet>
  <aps>
    <get-download-status>
      <filter>
        <task-id>18</task-id>
      </filter>
    </get-download-status>
  </aps>
</packet>

Response A

Positive response may look as follows:

<packet>
  <aps>
    <get-download-status>
      <result>
        <status>ok</status>
        <filter-id>18</filter-id>
        <id>18</id>
        <task>
          <id>18</id>
          <finished>
            <package-id>13</package-id>
          </finished>
        </task>
      </result>
    </get-download-status>
  </aps>
</packet>

Response B

Such response is received in case a download task did not start or finished with errors.

<packet>
  <aps>
    <get-download-status>
      <result>
        <status>ok</status>
        <filter-id>18</filter-id>
        <id>18</id>
        <task>
          <id>18</id>
          <finished>
            <error>Cannot download package from catalog</error>
          </finished>
        </task>
      </result>
    </get-download-status>
  </aps>
</packet>

Response C

Such negative response is received in case a download task with the requested ID does not exist.

<packet>
  <aps>
    <get-download-status>
      <result>
        <status>error</status>
        <errcode>1013</errcode>
        <errtext>Download task with id 18 not found</errtext>
        <filter-id>181</filter-id>
      </result>
    </get-download-status>
  </aps>
</packet>
Getting status of all download tasks within a current download transaction

This packet requests status of all download tasks within a current download transaction.

<packet>
  <aps>
    <get-download-status>
      <filter/>
    </get-download-status>
  </aps>
</packet>

Response A

Such response is received from Linux server where the transaction with tree tasks is run: one task is finished, one is in progress and one is queued.

<packet>
  <aps>
    <get-download-status>
      <result>
        <status>ok</status>
        <filter-id>10</filter-id>
        <id>10</id>
        <task>
          <id>10</id>
          <finished>
            <package-id>5</package-id>
          </finished>
        </task>
      </result>
      <result>
        <status>ok</status>
        <filter-id>11</filter-id>
        <id>11</id>
        <task>
          <id>11</id>
          <in-progress>
            <total>3584225</total>
            <completed>2458</completed>
            <current />
          </in-progress>
        </task>
      </result>
      <result>
        <status>ok</status>
        <filter-id>12</filter-id>
        <id>12</id>
        <task>
          <id>12</id>
          <in-progress>
            <total>45888236</total>
            <completed>0</completed>
          </in-progress>
        </task>
      </result>
    </get-download-status>
  </aps>
</packet>

Response B

Such response is received from Windows server when a transaction is run:

<packet>
  <aps>
    <get-download-status>
      <result>
        <status>ok</status>
        <filter-id>38</filter-id>
        <id>38</id>
        <task>
          <id>38</id>
          <in-progress>
            <total>0</total>
            <completed>0</completed>
          </in-progress>
        </task>
      </result>
    </get-download-status>
  </aps>
</packet>

Response C

Such response is received when there is no download transaction running.

<packet>
  <aps>
    <get-download-status>
      <result>
        <status>ok</status>
      </result>
    </get-download-status>
  </aps>
</packet>
 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.