DataSet Operation

ListAuthStorageConfig

ListAuthStorageConfig

Acquire the list of authentication configuration

Request path

GET /v1/auth-storage-configs

Request parameter

Query

Name	Type	Required	Descriptions
name	string	No	Configuration Name
limit	int	No	Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition
offset	int	No	The default is 0

Request instance

curl --location --request GET '{service}/v1/auth-storage-configs?name=aws_1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
    "configs": [
        {
            "name": "aws_1",
            "type": "s3",
            "endpoint": "s3.cn-northwest-1.amazonaws.com.cn",
            "accesskeyId": "AKIKU7KYZCWGOTEV5GNE",
            "bucketName": "graviti-210415"
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}

CreateDataset

Create a dataset

Create a TensorBay dataset with version control. The dataset name must be unique

Request path

POST /v1/datasets

Request parameter

Body

Name	Type	Required	Descriptions
name	string	Yes	Dataset name
type	int	No	The default is 0, 0-normal dataset; 1-Fusion dataset
storageConfig	object	No	Create parameters for using authenticated datasets; mutually exclusive with regions
├─name	string	Yes	Configuration name
├─name	path	No	Create storage path for datasets

Request instance

curl --location --request POST '{service}/v1/datasets' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "my first dataset",
   "type": 0,
   "storageConfig": {
        "name": "aws_1",
        "path": "graviti"
    }
}'

Output

# Response status
HttpStatus 201
# Response result
{
    "id": "154e35bae8954f09969ef8c9445efd2c"
}

• id: the ID of the created dataset

DeleteDataset

Delete a dataset

DELETE /v1/datasets/{id}

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Body

Name	Type	Required	Descriptions
commit	string	No	Commit ID or commit tag

Request instance

curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'

Output

# Response status
HttpStatus 200
# Response result
{}

UpdateDataset

Update dataset information

PATCH /v1/datasets/{id}

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Body

Name	Type	Required	Descriptions
name	string	No	dataset name, and the provided value cannot be the empty value "".

Request instance

curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'\
--data-raw '{
    "name": "my dataset",
}'

Output

# Response status
HttpStatus 200
# Response result
{}

ListDataset

List datasets

Return the list of datasets owned by the user:

• Individual users acquire the list of datasets under their personal accounts

• Team users acquire the list of datasets under their enterprise accounts

Request path

GET /v1/datasets

Request parameter

Query

Name	Type	Required	Descriptions
limit	int	No	Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition
offset	int	No	The default is 0
name	string	No	Dataset name
needFuzzyQuery	bool	No	If true, fuzzy query of the dataset name is supported.
sortBy	string	No	Currently sorting is based on created_at and updated_at while entering other content will return InvalidParamsValue.
orderBy	string	No	The default is desc (descending order). The valid content is asc (ascending order) and desc

Request instance

curl --location --request GET '{service}/v1/datasets?offset=0&limit=10'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
    "datasets": [
      {
        "id": "154e35bae8954f09969ef8c9445efd2c",
        "name": "my-great-data-set",
        "defaultBranch": "main",
        "type": 0,
        "updateTime": 1604977282,
        "owner": ""
      }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}

• datasets: List of datasets

  • id: Dataset ID

  • name: Dataset name

  • defaultBranch: default branch name

  • type: the default is 0, 0-normal dataset, 1-Fusion dataset

GetDataset

Request path

GET /v1/datasets/{id}

Request parameter

PATH

Name	Descriptions	Value
id	Yes	Dataset ID

Request instance

curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
    "name": "my-great-data-set",
    "type": 1,
    "defaultBranch": "main",
    "commitId": "00000000000000000000000000000000",
    "updateTime": 1604977282,
    "owner": ""
}

CreateBranch

Create a branch

Create a branch

Request path

POST /v1/datasets/{id}/branches

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Query

Name	Type	Required	Descriptions
name	string	Yes	The name of the created branch
commit	string	Yes	The commit that branch is based on. It can be commit ID, commit tag, or branch name

Request instance

curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json'\
--data-raw '{
  "name": main2,
  "commit": "fde63f357daf46088639e9f57fd81cad"
}'

Output

# Response status
HttpStatus 201
# Response result
{}

DeleteBranch

Delete branch

Delete branch

Request path

DELETE /v1/datasets/{id}/branches

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Query

Name	Type	Required	Descriptions
name	string	Yes	Branch name

Request instance

curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json'\
--data-raw '{
  "name": main2
}'

Output

# Response status
HttpStatus 200
# Response result
{}

ListBranch

Acquire a branch list

Acquire a list of dataset branches

Request path

GET /v1/datasets/{id}/branches

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Query

Name	Type	Required	Descriptions
limit	int	No	Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition
offset	int	No	The default is 0

Request instance

curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
    "branches": [
        {
            "name": "main",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "committer": {
                "name": "graviti",
                "date": 1616579313
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}

CreateDraft

Create a dataset draft

Create a TensorBay dataset draft. Only one draft can be created on a branch

Request path

POST /v1/datasets/{id}/drafts

Request parameter

Path

Name	Required	Descriptions
id	Yes	Dataset ID

Body

Name	Type	Required	Descriptions
title	string	No	Draft name
branchName	string	No	Branch name. The default branch is named as main

Request instance

curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "my first draft",
  "branchName": "main"
}'

Output

# Response status
HttpStatus 201
# Response result
{
    "draftNumber": 1
}

• draftNumber: draft number

ListDraft

Acquire a list of dataset drafts

Acquire a list of dataset drafts

Request path

GET /v1/datasets/{id}/drafts

Request parameter

Path

Name	Required	Descriptions
id	Yes	Dataset ID

Query

Name	Type	Required	Descriptions
limit	int	No	Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition
offset	int	No	The default is 0

Request instance

curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
  "drafts": [
    {
      "draftNumber": "1",
      "branchName": "main",
      "title": "my first draft"
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}

CommitDataset

Commit a dataset

Update a dataset with a pending status to a committed status. Once a dataset is published, it cannot be modified.

Request path

POST /v1/datasets/{id}

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Body

Name	Type	Required	Descriptions
draftNumber	int	Yes	Draft number
title	string	yes	The number of characters of the submitted title should be less than 255
tag	string	No	Dataset version tag. The number of characters should range from 2 to 80

Request instance

curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": "1",
  "title": "checkout a new version dataset",
  "tag": "v1.0"
}'

Output

# Response status
HttpStatus 200
# Response result
{
  "commitId": "fde63f357daf46088639e9f57fd81cad"
}

ListCommit

list commits

Acquire a list of dataset commits

Request path

GET /v1/datasets/{id}/commits

Request parameter Path

Name	Descriptions	Value
id	Yes	Dataset ID

Query

Name	Type	Required	Descriptions
commit	string	No	Commit ID, commit tag, or branch name. The default is the default branch
limit	int	No	The default is set to 128. The maximum value for a single time is 128
offset	int	No	The default is 0

Request instance

curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/commits?commit=main&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
  "commits": [
    {
      "parentCommitId": "0d213a06a85d46fa8662946bdb1afe7e",
      "commitId": "fde63f357daf46088639e9f57fd81cad",
      "title": "checkout a new version dataset",
      "committer": {
        "date": 1617268600,
        "name": "graviti"
      }
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}

CreateTag

Create a tag

Create a tag

Request path

POST /v1/datasets/{id}/tags

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Body

Name	Type	Required	Descriptions
commit	string	Yes	Commit ID, commit tag, or branch name
name	string	Yes	Tag name. The number of characters should range from 2 to 80

Request instance

curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "commit": "fde63f357daf46088639e9f57fd81cad",
  "name": "v1"
}'

Output

# Response status
HttpStatus 201
# Response result
{}

DeleteTag

Delete a tag

Delete a tag

Request path

DELETE /v1/datasets/{id}/tags

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Body

Name	Type	Required	Descriptions
name	string	Yes	tag name

Request instance

curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "v1"
}'

Output

# Response status
HttpStatus 200
# Response result
{}

ListTag

List tags

Acquire a list of dataset tags

Request path

GET /v1/datasets/{id}/tags

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Query

Name	Type	Required	Descriptions
name	string	否	tag name
limit	int	No	The default is set to 128. The maximum value for a single time is 128
offset	int	No	The default is 0

Request instance

curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags?name=v1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
    "tags": [
        {
            "name": "v1",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "committer": {
                "name": "graviti",
                "date": 1617268600
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}

updateNote

Update a dataset note

Update a dataset note

Request path

PATCH /v1/datasets/{id}/notes

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Body

Name	Type	Required	Descriptions
draftNumber	int	Yes	draft number
binPointCloudFields	string[]	No	Dimension name of the point cloud in bin format
isContinuous	bool	No	Is it continuous

Request instance

curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": 1,
  "fileFormat": {
    "draftNumber": 1,
    "binPointCloudFields": [
       "X",
       "Y",
       "Z",
       "Intensity"
    ],
    "isContinuous": true
}'

Output

# Response status
HttpStatus 200
# Response result
{}

GetNote

Get note

Get the note of a dataset

Request path

GET /v1/datasets/{id}/notes

Request parameter

Path

Name	Descriptions	Value
id	Yes	Dataset ID

Query

Name	Type	Required	Descriptions
draftNumber	int	No	Draft number. Only one of draft and commit should exist, but they should not exist at the same time
commit	string	No	Commit ID, commit tag, or branch name

Request instance

curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes?draftNumber=1' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 

Output

# Response status
HttpStatus 200
# Response result
{
    "isContinuous": true，
    "binPointCloudFields": [
        "X",
        "Y",
        "Z",
        "Intensity"
    ]
}