Download all files from a directory

Entire directories can be downloaded as a single, compressed ZIP file by using the create directory archive endpoint.

Data Ocean creates a downloadable file with a given target path and uploads zipped source directory asynchronously. Users can then download the archive file as normal.

To download an entire directory:

Create an archive file.
Check for job completion.
Download the archive file.

Note that the cloud provider of all files in the source directory must match the provider of the new archive file, i.e. all in AWS regions or all in Azure regions.

Create an archive of the directory

This request will automatically trigger an asynchronous job that will compress and upload the source directory to the target file.

API CALL:

POST {base URL}/directories

HEADERS:
- Accept: application/json
- Content-Type: application/json
- Authorization: Bearer (bearer token)
BODY:
- directory:
  - path: path of the source directory
  —OR—
  
  id: ID of the source directory
- file:
  - path: name of file and location of file
  - regions: regions
  - restricted_access: whether download link expires or not
  - expires_at: when the file is automatically deleted
  - metadata: additional client information
  - acl: TRN Trimble Resource Name (TRN). A TRN is a unique string identifying an instance of a resource type. It is of the form trn:::. permission mapping
- RESPONSE:
  - job:
    - id: id of async job, can be checked for completion
  - file: usual file response attributes

Example request body:

Copy; “javascript:void(0);”)

{
   "directory": {
       "path": "/dir1/exampledirectory"
   },
   "file": {
       "path": "/archive-dirs/exampledirectory.zip",
       "regions": ["us1"]
   }
}

Example response body:

Copy; “javascript:void(0);“)

{
   "file": {
       "acl": {},
       "application_id": "66251cb7-cd72-4577-a7b6-2aa956f9317d",
       "created_at": "2023-02-07T19:26:30.428+00:00",
       "expires_at": "2023-03-09T19:26:30.000+00:00",
       "fileset": false,
       "id": "760274db-6531-4118-9197-ff49406d6e8c",
       "malware_status": "UNSCANNED",
       "md5": null,
       "metadata": {},
       "multipart": false,
       "owner_id": "66251cb7-cd72-4577-a7b6-2aa956f9317d",
       "path": "66251cb7cd724577a7b62aa956f9317d:/archive-dirs/exampledirectory.zip",
       "region_preferences": [
           "us1"
       ],
       "regions": [],
       "restricted_access": true,
       "size": null,
       "status": "ARCHIVE_PROCESSING",
       "updated_at": "2023-02-07T19:26:30.428+00:00",
       "version": 1
   },
   "job": {
       "id": "74a1ccc4-9853-4dcd-8090-1d71090b11f3"
   }
}

Check for job completion

GET {base URL}/files/{file id}

Check for status: “AVAILABLE”.

—OR—

GET {base URL}/jobs/{job id}

Check for status: “COMPLETED”.

Download the archive file

GET {base_URL}/files/{file id}

Acquire the download URL.

GET {download URL}

Download the file from the download URL.

For more information on working with directories, see Directories in the API specification.

Reference Materials

Data Ocean API definition