Struct ResourceDescriptor

#[non_exhaustive]
pub struct ResourceDescriptor {
    pub type: String,
    pub pattern: Vec<String>,
    pub name_field: String,
    pub history: History,
    pub plural: String,
    pub singular: String,
    pub style: Vec<Style>,
}

A simple descriptor of a resource type.

ResourceDescriptor annotates a resource message (either by means of a protobuf annotation or use in the service config), and associates the resource’s schema, the resource type, and the pattern of the resource name.

Example:

message Topic {
  // Indicates this message defines a resource schema.
  // Declares the resource type in the format of {service}/{kind}.
  // For Kubernetes resources, the format is {api group}/{kind}.
  option (google.api.resource) = {
    type: "pubsub.googleapis.com/Topic"
    pattern: "projects/{project}/topics/{topic}"
  };
}

The ResourceDescriptor Yaml config will look like:

resources:
- type: "pubsub.googleapis.com/Topic"
  pattern: "projects/{project}/topics/{topic}"

Sometimes, resources have multiple patterns, typically because they can live under multiple parents.

Example:

message LogEntry {
  option (google.api.resource) = {
    type: "logging.googleapis.com/LogEntry"
    pattern: "projects/{project}/logs/{log}"
    pattern: "folders/{folder}/logs/{log}"
    pattern: "organizations/{organization}/logs/{log}"
    pattern: "billingAccounts/{billing_account}/logs/{log}"
  };
}

The ResourceDescriptor Yaml config will look like:

resources:
- type: 'logging.googleapis.com/LogEntry'
  pattern: "projects/{project}/logs/{log}"
  pattern: "folders/{folder}/logs/{log}"
  pattern: "organizations/{organization}/logs/{log}"
  pattern: "billingAccounts/{billing_account}/logs/{log}"

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

type: String

The resource type. It must be in the format of {service_name}/{resource_type_kind}. The resource_type_kind must be singular and must not include version numbers.

Example: storage.googleapis.com/Bucket

The value of the resource_type_kind must follow the regular expression /[A-Za-z][a-zA-Z0-9]+/. It should start with an upper case character and should use PascalCase (UpperCamelCase). The maximum number of characters allowed for the resource_type_kind is 100.

pattern: Vec<String>

Optional. The relative resource name pattern associated with this resource type. The DNS prefix of the full resource name shouldn’t be specified here.

The path pattern must follow the syntax, which aligns with HTTP binding syntax:

Template = Segment { "/" Segment } ;
Segment = LITERAL | Variable ;
Variable = "{" LITERAL "}" ;

Examples:

- "projects/{project}/topics/{topic}"
- "projects/{project}/knowledgeBases/{knowledge_base}"

The components in braces correspond to the IDs for each resource in the hierarchy. It is expected that, if multiple patterns are provided, the same component name (e.g. “project”) refers to IDs of the same type of resource.

name_field: String

Optional. The field on the resource that designates the resource name field. If omitted, this is assumed to be “name”.

history: History

Optional. The historical or future-looking state of the resource pattern.

Example:

// The InspectTemplate message originally only supported resource
// names with organization, and project was added later.
message InspectTemplate {
  option (google.api.resource) = {
    type: "dlp.googleapis.com/InspectTemplate"
    pattern:
    "organizations/{organization}/inspectTemplates/{inspect_template}"
    pattern: "projects/{project}/inspectTemplates/{inspect_template}"
    history: ORIGINALLY_SINGLE_PATTERN
  };
}

plural: String

The plural name used in the resource name and permission names, such as ‘projects’ for the resource name of ‘projects/{project}’ and the permission name of ‘cloudresourcemanager.googleapis.com/projects.get’. One exception to this is for Nested Collections that have stuttering names, as defined in AIP-122, where the collection ID in the resource name pattern does not necessarily directly match the plural value.

It is the same concept of the plural field in k8s CRD spec https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/

Note: The plural form is required even for singleton resources. See https://aip.dev/156

singular: String

The same concept of the singular field in k8s CRD spec https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/ Such as “project” for the resourcemanager.googleapis.com/Project type.

style: Vec<Style>

Style flag(s) for this resource. These indicate that a resource is expected to conform to a given style. See the specific style flags for additional information.

Implementations

impl ResourceDescriptor

pub fn set_type<T: Into<String>>(self, v: T) -> Self

Sets the value of r#type.

pub fn set_name_field<T: Into<String>>(self, v: T) -> Self

Sets the value of name_field.

pub fn set_history<T: Into<History>>(self, v: T) -> Self

Sets the value of history.

pub fn set_plural<T: Into<String>>(self, v: T) -> Self

Sets the value of plural.

pub fn set_singular<T: Into<String>>(self, v: T) -> Self

Sets the value of singular.

pub fn set_pattern<T, V>(self, v: T) -> Self

where T: IntoIterator<Item = V>, V: Into<String>,

Sets the value of pattern.

pub fn set_style<T, V>(self, v: T) -> Self

where T: IntoIterator<Item = V>, V: Into<Style>,

Sets the value of style.

Trait Implementations

impl Clone for ResourceDescriptor

fn clone(&self) -> ResourceDescriptor

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ResourceDescriptor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ResourceDescriptor

fn default() -> ResourceDescriptor

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ResourceDescriptor

where ResourceDescriptor: Default,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Message for ResourceDescriptor

fn typename() -> &'static str

The typename of this message.

impl PartialEq for ResourceDescriptor

fn eq(&self, other: &ResourceDescriptor) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ResourceDescriptor

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ResourceDescriptor