Chapter 12. CollectionService
Chapter 12. CollectionService 12.1. GetCollectionCount GET /v1/collectionscount 12.1.1. Description 12.1.2. Parameters 12.1.2.1. Query Parameters Name Description Required Default Pattern query.query - null query.pagination.limit - null query.pagination.offset - null query.pagination.sortOption.field - null query.pagination.sortOption.reversed - null query.pagination.sortOption.aggregateBy.aggrFunc - UNSET query.pagination.sortOption.aggregateBy.distinct - null 12.1.3. Return Type V1GetCollectionCountResponse 12.1.4. Content Type application/json 12.1.5. Responses Table 12.1. HTTP Response Codes Code Message Datatype 200 A successful response. V1GetCollectionCountResponse 0 An unexpected error response. GooglerpcStatus 12.1.6. Samples 12.1.7. Common object reference 12.1.7.1. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.1.7.2. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.1.7.2.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.1.7.3. V1GetCollectionCountResponse Field Name Required Nullable Type Description Format count Integer int32 12.2. DryRunCollection POST /v1/collections/dryrun 12.2.1. Description 12.2.2. Parameters 12.2.2.1. Body Parameter Name Description Required Default Pattern body V1DryRunCollectionRequest X 12.2.3. Return Type V1DryRunCollectionResponse 12.2.4. Content Type application/json 12.2.5. Responses Table 12.2. HTTP Response Codes Code Message Datatype 200 A successful response. V1DryRunCollectionResponse 0 An unexpected error response. GooglerpcStatus 12.2.6. Samples 12.2.7. Common object reference 12.2.7.1. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.2.7.2. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.2.7.2.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.2.7.3. StorageBooleanOperator Enum Values OR AND 12.2.7.4. StorageListDeployment Field Name Required Nullable Type Description Format id String hash String uint64 name String cluster String clusterId String namespace String created Date date-time priority String int64 12.2.7.5. StorageMatchType Enum Values EXACT REGEX 12.2.7.6. StorageResourceSelector Field Name Required Nullable Type Description Format rules List of StorageSelectorRule rules resolve as a conjunction (AND). 12.2.7.7. StorageRuleValue Field Name Required Nullable Type Description Format value String matchType StorageMatchType EXACT, REGEX, 12.2.7.8. StorageSelectorRule Field Name Required Nullable Type Description Format fieldName String operator StorageBooleanOperator OR, AND, values List of StorageRuleValue values resolve as a conjunction (AND) or disjunction (OR) depending on operator. For MVP, only OR is supported from UX standpoint. 12.2.7.9. V1AggregateBy Field Name Required Nullable Type Description Format aggrFunc V1Aggregation UNSET, COUNT, MIN, MAX, distinct Boolean 12.2.7.10. V1Aggregation Enum Values UNSET COUNT MIN MAX 12.2.7.11. V1CollectionDeploymentMatchOptions Field Name Required Nullable Type Description Format withMatches Boolean filterQuery V1RawQuery 12.2.7.12. V1DryRunCollectionRequest Field Name Required Nullable Type Description Format name String id String description String resourceSelectors List of StorageResourceSelector embeddedCollectionIds List of string options V1CollectionDeploymentMatchOptions 12.2.7.13. V1DryRunCollectionResponse Field Name Required Nullable Type Description Format deployments List of StorageListDeployment 12.2.7.14. V1Pagination Field Name Required Nullable Type Description Format limit Integer int32 offset Integer int32 sortOption V1SortOption sortOptions List of V1SortOption This field is under development. It is not supported on any REST APIs. 12.2.7.15. V1RawQuery RawQuery represents the search query string. The format of the query string is "<field name>:<value,value,... ><field name>:<value, value,...>... " For example: To search for deployments named "central" and "sensor" in the namespace "stackrox", the query string would be "Deployment:central,sensor+Namespace:stackrox" RawQuery is used in ListAPIs to search for a particular object. Field Name Required Nullable Type Description Format query String pagination V1Pagination 12.2.7.16. V1SortOption Field Name Required Nullable Type Description Format field String reversed Boolean aggregateBy V1AggregateBy 12.3. ListCollections GET /v1/collections 12.3.1. Description 12.3.2. Parameters 12.3.2.1. Query Parameters Name Description Required Default Pattern query.query - null query.pagination.limit - null query.pagination.offset - null query.pagination.sortOption.field - null query.pagination.sortOption.reversed - null query.pagination.sortOption.aggregateBy.aggrFunc - UNSET query.pagination.sortOption.aggregateBy.distinct - null 12.3.3. Return Type V1ListCollectionsResponse 12.3.4. Content Type application/json 12.3.5. Responses Table 12.3. HTTP Response Codes Code Message Datatype 200 A successful response. V1ListCollectionsResponse 0 An unexpected error response. GooglerpcStatus 12.3.6. Samples 12.3.7. Common object reference 12.3.7.1. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.3.7.2. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.3.7.2.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.3.7.3. ResourceCollectionEmbeddedResourceCollection Field Name Required Nullable Type Description Format id String 12.3.7.4. StorageBooleanOperator Enum Values OR AND 12.3.7.5. StorageMatchType Enum Values EXACT REGEX 12.3.7.6. StorageResourceCollection Field Name Required Nullable Type Description Format id String name String description String createdAt Date date-time lastUpdated Date date-time createdBy StorageSlimUser updatedBy StorageSlimUser resourceSelectors List of StorageResourceSelector resource_selectors resolve as disjunction (OR) with each-other and with selectors from embedded_collections . For MVP, the size of resource_selectors will at most be 1 from UX standpoint. embeddedCollections List of ResourceCollectionEmbeddedResourceCollection 12.3.7.7. StorageResourceSelector Field Name Required Nullable Type Description Format rules List of StorageSelectorRule rules resolve as a conjunction (AND). 12.3.7.8. StorageRuleValue Field Name Required Nullable Type Description Format value String matchType StorageMatchType EXACT, REGEX, 12.3.7.9. StorageSelectorRule Field Name Required Nullable Type Description Format fieldName String operator StorageBooleanOperator OR, AND, values List of StorageRuleValue values resolve as a conjunction (AND) or disjunction (OR) depending on operator. For MVP, only OR is supported from UX standpoint. 12.3.7.10. StorageSlimUser Field Name Required Nullable Type Description Format id String name String 12.3.7.11. V1ListCollectionsResponse Field Name Required Nullable Type Description Format collections List of StorageResourceCollection 12.4. DeleteCollection DELETE /v1/collections/{id} 12.4.1. Description 12.4.2. Parameters 12.4.2.1. Path Parameters Name Description Required Default Pattern id X null 12.4.3. Return Type Object 12.4.4. Content Type application/json 12.4.5. Responses Table 12.4. HTTP Response Codes Code Message Datatype 200 A successful response. Object 0 An unexpected error response. GooglerpcStatus 12.4.6. Samples 12.4.7. Common object reference 12.4.7.1. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.4.7.2. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.4.7.2.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.5. GetCollection GET /v1/collections/{id} 12.5.1. Description 12.5.2. Parameters 12.5.2.1. Path Parameters Name Description Required Default Pattern id X null 12.5.2.2. Query Parameters Name Description Required Default Pattern options.withMatches - null options.filterQuery.query - null options.filterQuery.pagination.limit - null options.filterQuery.pagination.offset - null options.filterQuery.pagination.sortOption.field - null options.filterQuery.pagination.sortOption.reversed - null options.filterQuery.pagination.sortOption.aggregateBy.aggrFunc - UNSET options.filterQuery.pagination.sortOption.aggregateBy.distinct - null 12.5.3. Return Type V1GetCollectionResponse 12.5.4. Content Type application/json 12.5.5. Responses Table 12.5. HTTP Response Codes Code Message Datatype 200 A successful response. V1GetCollectionResponse 0 An unexpected error response. GooglerpcStatus 12.5.6. Samples 12.5.7. Common object reference 12.5.7.1. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.5.7.2. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.5.7.2.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.5.7.3. ResourceCollectionEmbeddedResourceCollection Field Name Required Nullable Type Description Format id String 12.5.7.4. StorageBooleanOperator Enum Values OR AND 12.5.7.5. StorageListDeployment Field Name Required Nullable Type Description Format id String hash String uint64 name String cluster String clusterId String namespace String created Date date-time priority String int64 12.5.7.6. StorageMatchType Enum Values EXACT REGEX 12.5.7.7. StorageResourceCollection Field Name Required Nullable Type Description Format id String name String description String createdAt Date date-time lastUpdated Date date-time createdBy StorageSlimUser updatedBy StorageSlimUser resourceSelectors List of StorageResourceSelector resource_selectors resolve as disjunction (OR) with each-other and with selectors from embedded_collections . For MVP, the size of resource_selectors will at most be 1 from UX standpoint. embeddedCollections List of ResourceCollectionEmbeddedResourceCollection 12.5.7.8. StorageResourceSelector Field Name Required Nullable Type Description Format rules List of StorageSelectorRule rules resolve as a conjunction (AND). 12.5.7.9. StorageRuleValue Field Name Required Nullable Type Description Format value String matchType StorageMatchType EXACT, REGEX, 12.5.7.10. StorageSelectorRule Field Name Required Nullable Type Description Format fieldName String operator StorageBooleanOperator OR, AND, values List of StorageRuleValue values resolve as a conjunction (AND) or disjunction (OR) depending on operator. For MVP, only OR is supported from UX standpoint. 12.5.7.11. StorageSlimUser Field Name Required Nullable Type Description Format id String name String 12.5.7.12. V1GetCollectionResponse Field Name Required Nullable Type Description Format collection StorageResourceCollection deployments List of StorageListDeployment 12.6. UpdateCollection PATCH /v1/collections/{id} 12.6.1. Description 12.6.2. Parameters 12.6.2.1. Path Parameters Name Description Required Default Pattern id X null 12.6.2.2. Body Parameter Name Description Required Default Pattern body CollectionServiceUpdateCollectionBody X 12.6.3. Return Type V1UpdateCollectionResponse 12.6.4. Content Type application/json 12.6.5. Responses Table 12.6. HTTP Response Codes Code Message Datatype 200 A successful response. V1UpdateCollectionResponse 0 An unexpected error response. GooglerpcStatus 12.6.6. Samples 12.6.7. Common object reference 12.6.7.1. CollectionServiceUpdateCollectionBody Field Name Required Nullable Type Description Format name String description String resourceSelectors List of StorageResourceSelector embeddedCollectionIds List of string 12.6.7.2. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.6.7.3. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.6.7.3.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.6.7.4. ResourceCollectionEmbeddedResourceCollection Field Name Required Nullable Type Description Format id String 12.6.7.5. StorageBooleanOperator Enum Values OR AND 12.6.7.6. StorageMatchType Enum Values EXACT REGEX 12.6.7.7. StorageResourceCollection Field Name Required Nullable Type Description Format id String name String description String createdAt Date date-time lastUpdated Date date-time createdBy StorageSlimUser updatedBy StorageSlimUser resourceSelectors List of StorageResourceSelector resource_selectors resolve as disjunction (OR) with each-other and with selectors from embedded_collections . For MVP, the size of resource_selectors will at most be 1 from UX standpoint. embeddedCollections List of ResourceCollectionEmbeddedResourceCollection 12.6.7.8. StorageResourceSelector Field Name Required Nullable Type Description Format rules List of StorageSelectorRule rules resolve as a conjunction (AND). 12.6.7.9. StorageRuleValue Field Name Required Nullable Type Description Format value String matchType StorageMatchType EXACT, REGEX, 12.6.7.10. StorageSelectorRule Field Name Required Nullable Type Description Format fieldName String operator StorageBooleanOperator OR, AND, values List of StorageRuleValue values resolve as a conjunction (AND) or disjunction (OR) depending on operator. For MVP, only OR is supported from UX standpoint. 12.6.7.11. StorageSlimUser Field Name Required Nullable Type Description Format id String name String 12.6.7.12. V1UpdateCollectionResponse Field Name Required Nullable Type Description Format collection StorageResourceCollection 12.7. CreateCollection POST /v1/collections 12.7.1. Description 12.7.2. Parameters 12.7.2.1. Body Parameter Name Description Required Default Pattern body V1CreateCollectionRequest X 12.7.3. Return Type V1CreateCollectionResponse 12.7.4. Content Type application/json 12.7.5. Responses Table 12.7. HTTP Response Codes Code Message Datatype 200 A successful response. V1CreateCollectionResponse 0 An unexpected error response. GooglerpcStatus 12.7.6. Samples 12.7.7. Common object reference 12.7.7.1. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.7.7.2. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.7.7.2.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.7.7.3. ResourceCollectionEmbeddedResourceCollection Field Name Required Nullable Type Description Format id String 12.7.7.4. StorageBooleanOperator Enum Values OR AND 12.7.7.5. StorageMatchType Enum Values EXACT REGEX 12.7.7.6. StorageResourceCollection Field Name Required Nullable Type Description Format id String name String description String createdAt Date date-time lastUpdated Date date-time createdBy StorageSlimUser updatedBy StorageSlimUser resourceSelectors List of StorageResourceSelector resource_selectors resolve as disjunction (OR) with each-other and with selectors from embedded_collections . For MVP, the size of resource_selectors will at most be 1 from UX standpoint. embeddedCollections List of ResourceCollectionEmbeddedResourceCollection 12.7.7.7. StorageResourceSelector Field Name Required Nullable Type Description Format rules List of StorageSelectorRule rules resolve as a conjunction (AND). 12.7.7.8. StorageRuleValue Field Name Required Nullable Type Description Format value String matchType StorageMatchType EXACT, REGEX, 12.7.7.9. StorageSelectorRule Field Name Required Nullable Type Description Format fieldName String operator StorageBooleanOperator OR, AND, values List of StorageRuleValue values resolve as a conjunction (AND) or disjunction (OR) depending on operator. For MVP, only OR is supported from UX standpoint. 12.7.7.10. StorageSlimUser Field Name Required Nullable Type Description Format id String name String 12.7.7.11. V1CreateCollectionRequest Field Name Required Nullable Type Description Format name String description String resourceSelectors List of StorageResourceSelector embeddedCollectionIds List of string 12.7.7.12. V1CreateCollectionResponse Field Name Required Nullable Type Description Format collection StorageResourceCollection 12.8. ListCollectionSelectors GET /v1/collections/selectors 12.8.1. Description 12.8.2. Parameters 12.8.3. Return Type V1ListCollectionSelectorsResponse 12.8.4. Content Type application/json 12.8.5. Responses Table 12.8. HTTP Response Codes Code Message Datatype 200 A successful response. V1ListCollectionSelectorsResponse 0 An unexpected error response. GooglerpcStatus 12.8.6. Samples 12.8.7. Common object reference 12.8.7.1. GooglerpcStatus Field Name Required Nullable Type Description Format code Integer int32 message String details List of ProtobufAny 12.8.7.2. ProtobufAny Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Example 2: Pack and unpack a message in Java. The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". 12.8.7.2.1. JSON representation The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example: If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]): Field Name Required Nullable Type Description Format @type String A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one \"/\" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration ). The name should be in a canonical form (e.g., leading \".\" is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http , https , or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, https is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one. Schemes other than http , https (or the empty scheme) might be used with implementation specific semantics. 12.8.7.3. V1ListCollectionSelectorsResponse Field Name Required Nullable Type Description Format selectors List of string
Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } Next available tag: 9 Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } Next available tag: 9 Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } Foo foo = ...; Any any; any.PackFrom(foo); if (any.UnpackTo(&foo)) { } Foo foo = ...; Any any = Any.pack(foo); if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } // or if (any.isSameTypeAs(Foo.getDefaultInstance())) { foo = any.unpack(Foo.getDefaultInstance()); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := anypb.New(foo) if err != nil { } foo := &pb.Foo{} if err := any.UnmarshalTo(foo); err != nil { } package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": <string>, "lastName": <string> } { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" }