GAD02: Resource Names 资源名称

[denghuiquan]

资源名称

目录
Full Resource Name 完整资源名称
RelativeResource Name 相对资源名称
Resource ID 资源ID
Collection ID 集合ID
Resource Name vs URL 资源名称与URL的差异
Resource Name as String 字符串资源名称

在面向资源的API中，资源是命名实体，资源名称是它们的标识符。每个资源必须有它唯一的资源名称。资源名称由资源本身的ID、任何父资源的ID和它的API服务名称组成。下面我们来看一下资源ID以及如何构造资源名称。

gRPC API应该使用scheme-lessURIS作为资源名称。他们通常遵循其余的URL约定和行为就像网络文件路径。他们可以很容易地映射到REST URLs：详情见标准方法部分。

一个集合是一种包含同类型子资源列表的特殊的资源。例如，目录是文件资源的集合。集合的资源ID称为集合ID。

资源名称是使用集合ID和资源ID分层组织的，用正斜杠分隔。如果资源包含子资源，子资源的名字是通过指定父资源名称后跟子资源的ID，用正斜杠分隔形成的。

例子1：存储服务有一个桶（bucket）集合，每个桶都有一个对象(object)集合:
API Service Name | Collection ID | Resource ID | Collection ID | Resource ID
//storage.googleapis.com | /buckets | /bucket-id | /objects | /object-id

例子2：一个邮件服务有一个用户集合。每个用户有一个设置子资源，同时设置子资源有一系列其他的子资源，包括customFrom:
API Service Name | Collection ID | Resource ID | Resource ID | Resource ID
//mail.googleapis.com | /users | /name@example.com | /settings | /customFrom

API生产者可以选择资源和集合ID的任何可接受值，只要它们在资源层次结构中是唯一的。您可以在下面找到更多选择适当的资源和集合ID的指导方针。

通过拆分资源名称，如名称、拆分（“/”）n，假设没有片段段包含任何正向斜杠，那么就可以得到单独的集合ID和资源ID。

---

完整资源名称

由DNS兼容的API服务名称和资源路径组成的无计划（scheme-less ）URI。资源路径也称为相对资源名称。例如：
"//library.googleapis.com/shelves/shelf1/books/book2"

API服务名称是为客户定位API服务端点的；它可能是一个指向内部唯一的服务的假DNS名称。如果API服务名称在上下文中是明显可见的，则通常使用相对资源名称。

---

相对资源名称

一个不是由”/“开头的URI路径（path-noscheme）。它标识API服务中的资源。例如:
"shelves/shelf1/books/book2"

---

资源ID

一个标识其父资源内的资源的非空URI片段（segment-nz-nc），请参见上面的例子。

资源名称中的尾随资源id可能有多个URI片段。例如:
Collection ID | Resource ID
files | /source/py/parser.py

API服务在可行的时候应该使用URL友好的资源ID。资源ID必须清楚地记录是否由客户机、服务器分配，或者不是。例如，文件名通常由客户端分配，而电子邮件ID通常由服务器分配。

---

集合ID

一个标识其父资源内的集合资源的非空URI段（segment-nz-nc），请参见上面的例子。

由于集合ID经常出现在生成的客户端库中，所以它们必须符合以下要求：

• 必须是有效的C / C++标识符。
• 必须用复数形式与小写开头的驼峰格式。
• 必须使用清晰简明的英语词汇。
• 避免或限制使用过于笼统的词汇。
  例如： RowValue好过Value。下列词汇应严格无条件避免：
• Element
• Entry
• Instance
• Item
• Object
• Resource
• Type
• Value

---

资源名称与URL的差异

虽然完整资源名称类似正常网址,他们却不是同样的东西。可以通过不同版本的API和不同的API协议暴露单个资源。完整的资源名称没有指定这些信息，因此必须将其映射到特定的协议和API版本以供实际使用。

通过REST API使用完整资源名称，必须在服务名称之前添加HTTPS方案将其转换为其他URL，在资源路径之前添加API主版本，和经URL转义后的资源路径。例如：

// This is a calendar event resource name.
*"//calendar.googleapis.com/users/john smith/events/123"*

// This is the corresponding HTTP URL.
*"https://calendar.googleapis.com/v3/users/john%20smith/events/123"*

---

字符串资源名称

谷歌API必须使用字符串来表示资源名称，除非向后兼容是一个问题。资源名称应像正常文件路径一样处理，它们不支持%编码。

对于资源定义，第一个字段应该是资源名称的字符串字段，它应该被称为名称。

注意：其他与名城相关字段应避免混淆的名字，如display_name，first_name，last_name，full_name。

例如：

service LibraryService {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{name=shelves/*/books/*}"
    };
  };
  rpc CreateBook(CreateBookRequest) returns (Book) {
    option (google.api.http) = {
      post: "/v1/{parent=shelves/*}/books"
      body: "book"
    };
  };
}

message Book {
  // Resource name of the book. It must have the format of "shelves/*/books/*".
  // For example: "shelves/shelf1/books/book2".
  string name = 1;

  // ... other properties
}

message GetBookRequest {
  // Resource name of a book. For example: "shelves/shelf1/books/book2".
  string name = 1;
}

message CreateBookRequest {
  // Resource name of the parent resource where to create the book.
  // For example: "shelves/shelf1".
  string parent = 1;
  // The Book resource to be created. Client must not set the `Book.name` field.
  Book book = 2;
}

注意：对于资源名称的一致性，前面的斜杠不能被任何URL模板变量捕获。例如，URL模板"/v1/{name=shelves/*/books/*}" 必须用"/v1{name=/shelves/*/books/*}"代替。

Editor huiquan @denghuiquan
2017-03-26 14:20pM.