DataSphere API overview
In DataSphere, you can perform all basic operations on resources and notebooks using both the UI and API.
The Yandex Cloud API manages resources using sets of gRPC calls and REST methods. For more information about their implementation and interaction specifics, see the Yandex Cloud API documentation.
Working with the community
With CommunityService calls and Community methods, you can create, update, and delete a community. You can also view a list of communities in a particular organization.
| Description | gRPC | REST |
|---|---|---|
| Creates a new community in the specified organization | Create | create |
| Updates a community | Update | update |
| Deletes a community | Delete | delete |
| Returns information about a community | Get | get |
| Returns a list of communities in the specified organization | List | list |
Example. Creating a community:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request POST \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/communities" \
--data '{ "organizationId": "<organization_ID>" }'
Example. Viewing a list of communities in an organization:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request GET \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/communities" \
--data '{ "organizationId": "<organization_ID>" }'
For more information about the Community methods, see the API documentation.
Example. Creating a community:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"organization_id": "<organization_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.CommunityService/Create
Example. Viewing a list of communities in an organization:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"organization_id": "<organization_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.CommunityService/List
For more information about the CommunityService calls, see the API documentation.
Working with projects
With ProjectService calls and Project methods, you can create, open, update, and delete a project. You can also view a list of projects in a particular community.
| Description | gRPC | REST |
|---|---|---|
| Creates a new project in the specified community | Create | create |
| Updates a project | Update | update |
| Deletes a project | Delete | delete |
| Opens a project | Open | open |
| Returns information about a project | Get | get |
| Retrieves the list of projects in the specified community | List | list |
Example. Creating a project:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request POST \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/projects" \
--data '{ "communityId": "<community_ID>" }'
Example. Viewing a list of community projects:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request GET \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/projects" \
--data '{ "communityId": "<community_ID>" }'
For more information about the Project methods, see the API documentation.
Example. Creating a project:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"community_id": "<community_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.ProjectService/Create
Example. Viewing a list of folder projects:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"community_id": "<community_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.ProjectService/List
For more information about the ProjectService calls, see the API documentation.
Working with notebooks
To run a notebook, you can use the Execute call or the execute method in ProjectService.
| Description | gRPC | REST |
|---|---|---|
| Runs the specified notebook | Execute | execute |
Example. Running the whole notebook:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request POST \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/projects/<project_ID>:execute" \
--data '{ "notebook_id": "<notebook_ID>" }'
To get the notebook ID, follow the Getting a notebook ID guide.
For more information about the Project methods, see the API documentation.
Example. Running the whole notebook:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"project_id": "<project_ID>", "target": "notebook_id", "notebook_id": "<notebook_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.ProjectService/Execute
To get the notebook ID, follow the Getting a notebook ID guide.
For more information about the ProjectService calls, see the API documentation.
Working with resources
Resource activation and deactivation
Each resource has its own group of API methods implemented in DataSphere. By calling the Activate and Deactivate methods of the corresponding group in a given project, you can activate and deactivate the resources as needed.
| Description | gRPC | REST |
|---|---|---|
| Activates a dataset | Activate | activate |
| Deactivates a dataset | Deactivate | deactivate |
| Activates an S3 connector | Activate | activate |
| Deactivates an S3 connector | Deactivate | deactivate |
| Activates a Docker image | Activate | activate |
Example. Activating a dataset:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request POST \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/dataset/activate" \
--data "{ \"datasetId\": \"<dataset_ID>\", \"projectId\": \"<project_ID>\" }"
Example. Deactivating a dataset:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request POST \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/dataset/deactivate" \
--data "{ \"datasetId\": \"<dataset_ID>\", \"projectId\": \"<project_ID>\" }"
For more information about the Dataset methods, see the API documentation.
Example. Activating a dataset:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d "{\"project_id\": \"<project_ID>\", \"dataset_id\": \"<dataset_ID>\"}" \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.DatasetService/Activate
Example. Deactivating a dataset:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d "{\"project_id\": \"<project_ID>\", \"dataset_id\": \"<dataset_ID>\"}" \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.DatasetService/Deactivate
For more information about the DatasetService calls, see the API documentation.
Adding and deleting resources
You can use the API to add and delete resources in a project (ProjectService, Project) or community (CommunityService, Community).
To enable your project to use another project's resources, you need to share the resource in a community and add it to your project.
| Description | gRPC | REST |
|---|---|---|
| Adds a resource to a community | AddResource | addResource |
| Deletes a resources from a community | RemoveResource | removeResource |
| Adds a resource to a project | AddResource | addResource |
| Deletes a resource from a project | RemoveResource | removeResource |
Example. Adding a resource to a project:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request POST \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/projects/<resource_ID>:addResource" \
--data "{ \"projectId\": \"<project_ID>\" }"
Example. Deleting a resource from a project:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request POST \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/projects/<resource_ID>:removeResource" \
--data "{ \"projectId\": \"<project_ID>\" }"
For more information about the Project methods, see the API documentation.
Example. Adding a resource to a project:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d "{\"project_id\": \"<project_ID>\", \"resource_id\": \"<resource_ID>\"}" \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.ProjectService/AddResource
Example. Deleting a resource from a project:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d "{\"project_id\": \"<project_ID>\", \"resource_id\": \"<resource_ID>\"}" \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.ProjectService/RemoveResource
For more information about the ProjectService calls, see the API documentation.
Access management
You can use the API to set up access to a project (ProjectService, Project) or community (CommunityService, Community).
| Description | gRPC | REST |
|---|---|---|
| Returns a list of access permissions for a project | ListAccessBindings | listAccessBindings |
| Sets up access to a project | SetAccessBindings | setAccessBindings |
| Updates access to a project | UpdateAccessBindings | updateAccessBindings |
| Returns a list of access permissions for a community | ListAccessBindings | listAccessBindings |
| Sets up access to a community | SetAccessBindings | setAccessBindings |
| Updates access to a community | UpdateAccessBindings | updateAccessBindings |
Example. Viewing a list of access permissions for a project:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request GET \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/projects/<resource_ID>:accessBindings"
Example. Return a list of access permissions for a community:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request GET \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/communities/<resource_ID>:accessBindings"
For more information about the Project and Community methods, see the API documentation.
Example. Viewing a list of access permissions for a project:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"resource_id": "<project_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.ProjectService/ListAccessBindings
Example. Return a list of access permissions for a community:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"resource_id": "<community_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.CommunityService/ListAccessBindings
For more information about the ProjectService and CommunityService methods, see the API documentation.
Managing consumption limits
You can use the API to set up consumption limits for a project (ProjectService, Project).
| Description | gRPC | REST |
|---|---|---|
| Returns a project's balance | GetUnitBalance | getUnitBalance |
| Sets a project's balance | SetUnitBalance | setUnitBalance |
Example. Getting a project's balance:
curl \
--header "Authorization: Bearer <IAM_token>" \
--request GET \
"https://datasphere.api.cloud.yandex.net/datasphere/v2/projects/<project_ID>:unitBalance"
For more information about the Project methods, see the API documentation.
Example. Getting a project's balance:
grpcurl \
-rpc-header "Authorization: Bearer <IAM_token>" \
-d '{"project_id": "<project_ID>"}' \
datasphere.api.cloud.yandex.net:443 \
yandex.cloud.datasphere.v2.ProjectService/GetUnitBalance
For more information about the ProjectService calls, see the API documentation.