Globus Connect Server API

The Globus Connect Server Manager API (GCS Manager API) runs on a Globus Connect Server Endpoint and allows management of the Endpoint, Storage Gateways, Collections, and other resources.

Unlike other Globus services, there is no single central API used to contact GCS Manager instances. Therefore, the GCSClient is always initialized with the FQDN (DNS name) of the GCS Endpoint. e.g. gcs = GCSClient("abc.def.data.globus.org")

Client

The primary interface for the GCS Manager API is the GCSClient class.

class globus_sdk.GCSClient(gcs_address: str, *, environment: Optional[str] = None, authorizer: Optional[globus_sdk.authorizers.base.GlobusAuthorizer] = None, app_name: Optional[str] = None, transport_params: Optional[Dict] = None)[source]

Bases: globus_sdk.client.BaseClient

A GCSClient provides communication with the GCS Manager API of a Globus Connect Server instance. For full reference, see the documentation for the GCS Manager API.

Unlike other client types, this must be provided with an address for the GCS Manager. All other arguments are the same as those for ~globus_sdk.BaseClient.

Parameters

gcs_address (str) – The FQDN (DNS name) or HTTPS URL for the GCS Manager API.

Methods

static get_gcs_endpoint_scopes(endpoint_id: Union[uuid.UUID, str]) globus_sdk.scopes.GCSEndpointScopeBuilder[source]

Given a GCS Endpoint ID, this helper constructs an object containing the scopes for that Endpoint.

Parameters

endpoint_id (UUID or str) – The ID of the Endpoint

See documentation for globus_sdk.scopes.GCSEndpointScopeBuilder for more information.

static get_gcs_collection_scopes(collection_id: Union[uuid.UUID, str]) globus_sdk.scopes.GCSCollectionScopeBuilder[source]

Given a GCS Collection ID, this helper constructs an object containing the scopes for that Collection.

Parameters

collection_id (UUID or str) – The ID of the Collection

See documentation for globus_sdk.scopes.GCSCollectionScopeBuilder for more information.

get_collection_list(*, include: Optional[Union[Iterable[str], str]] = None, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.gcs.response.IterableGCSResponse[source]

GET /collections

Parameters
  • include (str or iterable of str, optional) – Names of additional documents to include in the response

  • query_params (dict, optional) – Additional passthrough query parameters

List the Collections on an Endpoint

External Documentation

See List Collections in the API documentation for details.

get_collection(collection_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.gcs.response.UnpackingGCSResponse[source]

GET /collections/{collection_id}

Parameters
  • collection_id (str or UUID) – The ID of the collection to lookup

  • query_params (dict, optional) – Additional passthrough query parameters

Lookup a Collection on an Endpoint

External Documentation

See Get Collection in the API documentation for details.

create_collection(collection_data: Union[Dict[str, Any], globus_sdk.services.gcs.data.CollectionDocument]) globus_sdk.services.gcs.response.UnpackingGCSResponse[source]

POST /collections

Create a collection. This is used to create either a mapped or a guest collection. When created, a collection:administrator role for that collection will be created using the caller’s identity.

In order to create a guest collection, the caller must have an identity that matches the Storage Gateway policies.

In order to create a mapped collection, the caller must have an endpoint:administrator or endpoint:owner role.

Parameters

collection_data (dict or CollectionDocument) – The collection document for the new collection

External Documentation

See Create Collection in the API documentation for details.

update_collection(collection_id: Union[uuid.UUID, str], collection_data: Union[Dict[str, Any], globus_sdk.services.gcs.data.CollectionDocument], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.services.gcs.response.UnpackingGCSResponse[source]

PATCH /collections/{collection_id}

Parameters
  • collection_id (str or UUID) – The ID of the collection to update

  • collection_data (dict or CollectionDocument) – The collection document for the modified collection

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Update Collection in the API documentation for details.

delete_collection(collection_id: Union[uuid.UUID, str], *, query_params: Optional[Dict[str, Any]] = None) globus_sdk.response.GlobusHTTPResponse[source]

DELETE /collections/{collection_id}

Parameters
  • collection_id (str or UUID) – The ID of the collection to delete

  • query_params (dict, optional) – Additional passthrough query parameters

External Documentation

See Delete Collection in the API documentation for details.

Helper Objects

class globus_sdk.services.gcs.data.CollectionDocument(*, data_type: Optional[str] = None, collection_base_path: Optional[str] = None, contact_email: Optional[str] = None, contact_info: Optional[str] = None, default_directory: Optional[str] = None, department: Optional[str] = None, description: Optional[str] = None, display_name: Optional[str] = None, identity_id: Optional[Union[uuid.UUID, str]] = None, info_link: Optional[str] = None, organization: Optional[str] = None, user_message: Optional[str] = None, user_message_link: Optional[str] = None, keywords: Optional[Iterable[str]] = None, disable_verify: Optional[bool] = None, enable_https: Optional[bool] = None, force_encryption: Optional[bool] = None, force_verify: Optional[bool] = None, public: Optional[bool] = None, additional_fields: Optional[Dict[str, Any]] = None)[source]

Bases: globus_sdk.utils.PayloadWrapper, abc.ABC

This is the base class for MappedCollectionDocument and GuestCollectionDocument.

Parameters common to both of those are defined and documented here.

Parameters
  • data_type (str, optional) – Explicitly set the DATA_TYPE value for this collection. Normally DATA_TYPE is deduced from the provided parameters and should not be set. To maximize compatibility with different versions of GCS, only set this value when necessary.

  • collection_base_path (str, optional) – The location of the collection on its underlying storage. For a mapped collection, this is an absolute path on the storage system named by the storage_gateway_id. For a guest collection, this is a path relative to the value of the root_path attribute on the mapped collection identified by the mapped_collection_id. This parameter is optional for updates but required when creating a new collection.

  • contact_email (str, optional) – Email address of the support contact for the collection

  • contact_info (str, optional) – Other contact information for the collection, e.g. phone number or mailing address

  • default_directory (str, optional) – Default directory when using the collection

  • department (str, optional) – The department which operates the collection

  • description (str, optional) – A text description of the collection

  • display_name (str, optional) – Friendly name for the collection

  • identity_id (str or UUID, optional) – The Globus Auth identity which acts as the owner of the collection

  • info_link (str, optional) – Link for more info about the collection

  • organization (str, optional) – The organization which maintains the collection

  • user_message (str, optional) – A message to display to users when interacting with this collection

  • user_message_link (str, optional) – A link to additional messaging for users when interacting with this collection

  • keywords (iterable of str, optional) – A list of keywords used to help searches for the collection

  • disable_verify (bool, optional) – Disable verification checksums on transfers to and from this collection

  • enable_https (bool, optional) – Enable or disable HTTPS support (requires a managed endpoint)

  • force_encryption (bool, optional) – When set to True, all transfers to and from the collection are always encrypted

  • force_verify (bool, optional) – Force verification checksums on transfers to and from this collection

  • public (bool, optional) – If True, the collection will be visible to other Globus users

  • additional_fields (dict, optional) – Additional data for inclusion in the collection document

class globus_sdk.services.gcs.data.GuestCollectionDocument(*, data_type: Optional[str] = None, collection_base_path: Optional[str] = None, contact_email: Optional[str] = None, contact_info: Optional[str] = None, default_directory: Optional[str] = None, department: Optional[str] = None, description: Optional[str] = None, display_name: Optional[str] = None, identity_id: Optional[Union[uuid.UUID, str]] = None, info_link: Optional[str] = None, organization: Optional[str] = None, user_message: Optional[str] = None, user_message_link: Optional[str] = None, keywords: Optional[Iterable[str]] = None, disable_verify: Optional[bool] = None, enable_https: Optional[bool] = None, force_encryption: Optional[bool] = None, force_verify: Optional[bool] = None, public: Optional[bool] = None, mapped_collection_id: Optional[Union[uuid.UUID, str]] = None, user_credential_id: Optional[Union[uuid.UUID, str]] = None, additional_fields: Optional[Dict[str, Any]] = None)[source]

Bases: globus_sdk.services.gcs.data.CollectionDocument

An object used to represent a Guest Collection for creation or update operations. The initializer supports all writable fields on Guest Collections but does not include read-only fields like id.

Because these documents may be used for updates, no fields are strictly required. However, GCS will require the following fields for creation:

  • mapped_collection_id

  • user_credential_id

  • collection_base_path

All parameters for CollectionDocument are supported in addition to the parameters below.

Parameters
  • mapped_collection_id (str or UUID) – The ID of the mapped collection which hosts this guest collection

  • user_credential_id (str or UUID) – The ID of the User Credential which is used to access data on this collection. This credential must be owned by the collection’s identity_id.

class globus_sdk.services.gcs.data.MappedCollectionDocument(*, data_type: Optional[str] = None, collection_base_path: Optional[str] = None, contact_email: Optional[str] = None, contact_info: Optional[str] = None, default_directory: Optional[str] = None, department: Optional[str] = None, description: Optional[str] = None, display_name: Optional[str] = None, identity_id: Optional[Union[uuid.UUID, str]] = None, info_link: Optional[str] = None, organization: Optional[str] = None, user_message: Optional[str] = None, user_message_link: Optional[str] = None, keywords: Optional[Iterable[str]] = None, disable_verify: Optional[bool] = None, enable_https: Optional[bool] = None, force_encryption: Optional[bool] = None, force_verify: Optional[bool] = None, public: Optional[bool] = None, storage_gateway_id: Optional[Union[uuid.UUID, str]] = None, domain_name: Optional[str] = None, sharing_users_allow: Optional[Iterable[str]] = None, sharing_users_deny: Optional[Iterable[str]] = None, sharing_restrict_paths: Optional[Dict[str, Any]] = None, allow_guest_collections: Optional[bool] = None, disable_anonymous_writes: Optional[bool] = None, policies: Optional[Dict[str, Any]] = None, additional_fields: Optional[Dict[str, Any]] = None)[source]

Bases: globus_sdk.services.gcs.data.CollectionDocument

An object used to represent a Mapped Collection for creation or update operations. The initializer supports all writable fields on Mapped Collections but does not include read-only fields like id.

Because these documents may be used for updates, no fields are strictly required. However, GCS will require the following fields for creation:

  • storage_gateway_id

  • collection_base_path

All parameters for CollectionDocument are supported in addition to the parameters below.

Parameters
  • storage_gateway_id (str or UUID, optional) – The ID of the storage gateway which hosts this mapped collection. This parameter is required when creating a collection.

  • domain_name (str, optional) – DNS name of the virtual host serving this collection

  • sharing_users_allow (iterable of str, optional) – Connector-specific usernames allowed to create guest collections

  • sharing_users_deny (iterable of str, optional) – Connector-specific usernames forbidden from creating guest collections

  • allow_guest_collections (bool, optional) – Enable or disable creation and use of Guest Collections on this Mapped Collection

  • disable_anonymous_writes (bool, optional) – Allow anonymous write ACLs on Guest Collections attached to this Mapped Collection. This option is only usable on non high-assurance collections

  • policies (dict, optional) – Connector-specific collection policies

  • sharing_restrict_paths (dict, optional) – A PathRestrictions document

Client Errors

When an error occurs, a GCSClient will raise this specialized type of error, rather than a generic GlobusAPIError.

class globus_sdk.GCSAPIError(r: requests.models.Response)[source]

Bases: globus_sdk.exc.api.GlobusAPIError

Error class for the GCS Manager API client

GCS Responses

class globus_sdk.services.gcs.response.IterableGCSResponse(response: Union[requests.models.Response, GlobusHTTPResponse], client: Optional[globus_sdk.BaseClient] = None, *, iter_key: Optional[str] = None)[source]

Bases: globus_sdk.response.IterableResponse

Response class for non-paged list oriented resources. Allows top level fields to be accessed normally via standard item access, and also provides a convenient way to iterate over the sub-item list in the data key:

>>> print("Path:", r["path"])
>>> # Equivalent to: for item in r["data"]
>>> for item in r:
>>>     print(item["name"], item["type"])
class globus_sdk.services.gcs.response.UnpackingGCSResponse(response: globus_sdk.response.GlobusHTTPResponse, match: Union[str, Callable[[dict], bool]])[source]

Bases: globus_sdk.response.GlobusHTTPResponse

An “unpacking” response looks for a “data” array in the response data, which is expected to have dict elements. The “data” is traversed until the first matching object is found, and this is presented as the data property of the response.

The full response data is available as full_data.

If the expected datatype is not found in the array, or the array is missing, the data will be the full response data (identical to full_data).

Parameters

match (str or callable) – Either a string containing a DATA_TYPE prefix, or an arbitrary callable which does the matching

property full_data: Any

The full, parsed JSON response data. None if the data cannot be parsed as JSON.