Artifacts#
Contents
Artifact Definition#
An artifact in Dioptra is a resource which represents a stored output of a job.
Artifact Attributes#
Task: (integer ID) The Artifact Task associated with the Artifact. The associated task will be used for serialization and deserialization (See: Artifact Tasks Reference).
Group: (integer ID) The Group that owns this Artifact and controls access permissions.
Plugin Snapshot: (integer ID) The Plugin Snapshot which contains the artifact task. The artifact is associated with a snapshot, and so even if the plugin changes, the artifact will still be loadable using the snapshot.
Artifact URI: (string) The URI representing the artifact’s location.
Job: (integer ID) The job the artifact should be associated with.
Optional Attributes#
Description: (string, optional) A text description of the Artifact’s purpose or contents. Defaults to empty.
System-Managed State#
ID: Unique identifier assigned upon creation.
Created On: Timestamp indicating when the Artifact was created.
Last Modified On: Timestamp indicating when the Artifact was last modified.
File Size: The size of the artifact.
Is Directory: Whether the artifact is a directory.
File URL: A link for downloading the artifact.
Retrieval Interfaces#
Artifacts can be retrieved via the Python Client or the RESTAPI. Alternatively, the Job Dashboard page of the UI has an Output Artifacts page where artifacts associated with a specific job can be viewed or downloaded.
Using Python Client#
Retrieve a list of artifact resources
- ArtifactsCollectionClient.get(group_id: int | None = None, index: int = 0, page_length: int = 10, sort_by: str | None = None, descending: bool | None = None, search: str | None = None) dioptra.client.artifacts.T[source]#
Get a list of artifacts.
- Parameters
group_id – The group id the artifacts belong to. If None, return artifacts from all groups that the user has access to. Optional, defaults to None.
index – The paging index. Optional, defaults to 0.
page_length – The maximum number of artifacts to return in the paged response. Optional, defaults to 10.
sort_by – The field to use to sort the returned list. Optional, defaults to None.
descending – Sort the returned list in descending order. Optional, defaults to None.
search – Search for artifacts using the Dioptra API’s query language. Optional, defaults to None.
- Returns
The response from the Dioptra API.
Retrieve an artifact using its ID
Retrieve the file listing associated with an artifact using its ID
Retrieve the contents of an artifact using its ID
- ArtifactsCollectionClient.get_contents(artifact_id: str | int, file_type: dioptra.client.utils.FileTypes | None = None, artifact_path: str | None = None, output_dir: pathlib.Path | None = None, file_stem: str = 'contents') pathlib.Path[source]#
Get the contents of an artifact with the given artifact resource id.
- Parameters
artifact_id – The artifact resource id, an integer.
file_type – if the artifact is a directory, this indicates the file type of the bundle that is returned, defaults to None. A value of None must be provided if the artifact is a file. If the artifact is a directory and None is provided, then a default of FileTypes.TAR_GZ is used.
artifact_path – if the artifact is a directory, then a value other than None indicates a path in the directory structure to retrieve. if the artifact is a file, None must be provided. All of the files for a directory artifact are returned if None is provided.
output_dir – the directory to save the downloaded artifact, defaults to None. If None, then the current working directory will be used.
file_stem – the file prefix or stem to use for the name of the downloaded file. Defaults to the value of “contents”.
- Returns
A path to where the contents are downloaded.
Using REST API#
Get a list of Artifacts
See the GET /api/v1/artifacts endpoint documentation for payload requirements.
Download the contents of an Artifact
See the GET /api/v1/artifacts/{int:id}/contents endpoint documentation for payload requirements.
Get a list of all files associated with an Artifact
See the GET /api/v1/artifacts/{int:id}/files endpoint documentation for payload requirements.
Registration Interfaces#
Artifacts are typically created automatically as an output of a job, through the use of the Artifact Output Graph section of an entrypoint.
They can also be created via the Python Client or the RESTAPI.
Using Python Client#
Create an Artifact
- ArtifactsCollectionClient.create(group_id: str | int, job_id: str | int, artifact_uri: str, plugin_snapshot_id: str | int | None = None, task_id: str | int | None = None, description: str | None = None) dioptra.client.artifacts.T[source]#
Creates an artifact and associates with an existing Job.
Both plugin_snapshot_id and must be None or not None. If None, then the artifact is unavailable for use as input into another job and may only be downloaded.
- Parameters
group_id – The id of the group that will own the artifact.
job_id – The id of the job that produced this artifact.
artifact_uri – The URI pointing to the location of the artifact.
plugin_snapshot_id – the plugin snapshot id of the plugin containing the artifact task used to serialize/deserialize the artifact, defaults to None.
task_id – the task id of the plugin artifact task used to serialize/deserialize the artifact, defaults to None
description – The description of the new artifact. Optional, defaults to None.
- Returns
The response from the Dioptra API.
Using REST API#
Artifacts can be created directly via the HTTP API.
Create an Artifact
See the POST /api/v1/artifacts endpoint documentation for payload requirements.