Shares provide users a way of collaborating on individual folders in a personal workspaces.
Rationale
📝 NOTE: This API follows the standard Resources API. We recommend that you have already read and understood the concepts described here.
This feature is currently implemented for backwards compatibility with UCloud. We don't currently recommend other providers implement this functionality. Nevertheless, we provide a few example to give you an idea of how to use this feature. We generally recommend that you use a full-blown project for collaboration.
This endpoint will determine all providers that which the authenticated user has access to, in the current workspace. A user has access to a product, and thus a provider, if the product is either free or if the user has been granted credits to use the product.
This request is sent by the client, if the client believes that initialization of resources might be needed. NOTE: This request might be sent even if initialization has already taken place. UCloud/Core does not check if initialization has already taken place, it simply validates the request.
The contents of this field depends almost entirely on the specific Resource that this field is managing. Typically, this will contain information such as:
A state value. For example, a compute Job might be RUNNING
Key metrics about the resource.
Related resources. For example, certain Resources are bound to another Resource in a mutually exclusive way, this should be listed in the status section.
Updates can optionally be fetched for a Resource. The updates describe how the Resource changes state over time. The current state of a Resource can typically be read from its status field. Thus, it is typically not needed to use the full update history if you only wish to know the current state of a Resource.
An update will typically contain information similar to the status field, for example:
A state value. For example, a compute Job might be RUNNING.
Paginated content can be requested with one of the following consistency guarantees, this greatly changes the semantics of the call:
Consistency
Description
PREFER
Consistency is preferred but not required. An inconsistent snapshot might be returned.
REQUIRE
Consistency is required. A request will fail if consistency is no longer guaranteed.
The consistency refers to if collecting all the results via the pagination API are consistent. We consider the results to be consistent if it contains a complete view at some point in time. In practice this means that the results must contain all the items, in the correct order and without duplicates.
If you use the PREFER consistency then you may receive in-complete results that might appear out-of-order and can contain duplicate items. UCloud will still attempt to serve a snapshot which appears mostly consistent. This is helpful for user-interfaces which do not strictly depend on consistency but would still prefer something which is mostly consistent.
The results might become inconsistent if the client either takes too long, or a service instance goes down while fetching the results. UCloud attempts to keep each next token alive for at least one minute before invalidating it. This does not mean that a client must collect all results within a minute but rather that they must fetch the next page within a minute of the last page. If this is not feasible and consistency is not required then PREFER should be used.
📝 NOTE: Services are allowed to ignore extra criteria of the request if the next token is supplied. This is needed in order to provide a consistent view of the results. Clients should provide the same criterion as they paginate through the results.