API endpoint base: https://pirca.arvadosapi.com/arvados/v1/groups
Object type: j7d0g
Example UUID: zzzzz-j7d0g-0123456789abcde
Groups provides a way to apply the same permissions to a set of Arvados objects. See permission model for details.
Each Group has, in addition to the Common resource fields:
Attribute | Type | Description | Example |
---|---|---|---|
name | string | ||
group_class | string | Type of group. This does not affect behavior, but determines how the group is presented in the user interface. For example, project indicates that the group should be displayed by Workbench and arv-mount as a project for organizing and naming objects. |
"project" null |
description | text | ||
properties | hash | User-defined metadata, may be used in queries using subproperty filters | |
writable_by | array | List of UUID strings identifying Users and other Groups that have write permission for this Group. Only users who are allowed to administer the Group will receive a full list. Other users will receive a partial list that includes the Group’s owner_uuid and (if applicable) their own user UUID. | |
trash_at | datetime | If trash_at is non-null and in the past, this group and all objects directly or indirectly owned by the group will be hidden from API calls. May be untrashed. |
|
delete_at | datetime | If delete_at is non-null and in the past, the group and all objects directly or indirectly owned by the group may be permanently deleted. |
|
is_trashed | datetime | True if trash_at is in the past, false if not. |
See Common resource methods for more information about create
, delete
, get
, list
, and update
.
Required arguments are displayed in green.
Retrieve a list of items owned by the group.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the group in question. | path | |
limit | integer (default 100) | Maximum number of items to return. | query | |
order | array | Attributes to use as sort keys to determine the order resources are returned, each optionally followed by asc or desc to indicate ascending or descending order. Sort within a resource type by prefixing the attribute with the resource name and a period. |
query | ["collections.modified_at desc"] |
filters | array | Conditions for filtering items. | query | [["uuid", "is_a", "arvados#job"]] |
recursive | boolean (default false) | Include items owned by subprojects. | query | true |
exclude_home_project | boolean (default false) | Only return items which are visible to the user but not accessible within the user’s home project. Use this to get a list of items that are shared with the user. | query | true |
Note: Because adding access tokens to manifests can be computationally expensive, the manifest_text
field is not included in listed collections. If you need it, request a list of collections with the filter ["owner_uuid", "=", GROUP_UUID]
, and "manifest_text"
listed in the select parameter.
Note: Use filters with the attribute format <item type>.<field name>
to filter items of a specific type. For example: ["pipeline_instances.state", "=", "Complete"]
to filter pipeline_instances
where state
is Complete
. All other types of items owned by this group will be unimpacted by this filter and will still be included.
Create a new Group.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
group | object | query | ||
async | boolean (default false) | Defer the permissions graph update by a configured number of seconds. (By default, async_permissions_update_interval is 20 seconds). On success, the response is 202 (Accepted). |
query | true |
Put a Group in the trash. This sets the trash_at
field to now
and delete_at
field to now
+ token TTL. A trashed group is invisible to most API calls unless the include_trash
parameter is true. All objects directly or indirectly owned by the Group are considered trashed as well.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group in question. | path |
Gets a Group’s metadata by UUID.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group in question. | path |
List groups.
See common resource list method.
show groups
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | path |
Update attributes of an existing Group.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group in question. | path | |
group | object | query | ||
async | boolean (default false) | Defer the permissions graph update by a configured number of seconds. (By default, async_permissions_update_interval is 20 seconds). On success, the response is 202 (Accepted). |
query | true |
Remove a Group from the trash. This sets the trash_at
and delete_at
fields to null
.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group to untrash. | path | |
ensure_unique_name | boolean (default false) | Rename project uniquely if untrashing it would fail with a unique name conflict. | query |
This endpoint returns the toplevel set of groups to which access is granted through a chain of one or more permission links rather than through direct ownership by the current user account. This is useful for clients which wish to browse the list of projects the user has permission to read which are not part of the “home” project tree.
When called with “include=owner_uuid” this also returns (in the “included” field) the objects that own those projects (users or non-project groups).
Specifically, the logic is:
select groups that are readable by current user AND (the owner_uuid is a user (but not the current user) OR the owner_uuid is not readable by the current user OR the owner_uuid is a group but group_class is not a project)
In addition to the “include” parameter this endpoint also supports the same parameters as the list method.
Argument | Type | Description | Location | Example |
---|---|---|---|---|
include | string | If provided with the value “owner_uuid”, this will return owner objects in the “included” field of the response. | query | ?include=owner_uuid |
The content of this documentation is licensed under the
Creative
Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the
Apache License, Version 2.0.