Ressourcennamen

In ressourcenorientierten APIs sind Ressourcen benannte Entitäten und Ressourcennamen ihre Kennungen. Jede Ressource muss einen eigenen eindeutigen Ressourcennamen haben. Der Ressourcenname besteht aus der ID der Ressource an sich, den IDs aller übergeordneten Ressourcen und dem API-Dienstnamen. In diesem Abschnitt werden Ressourcen-IDs und der Aufbau von Ressourcennamen erläutert.

In gRPC APIs sollten für Ressourcennamen schemalose URIs verwendet werden. Diese folgen generell den REST-URL-Namenskonventionen und verhalten sich ähnlich wie Netzwerkdateipfade. Die Zuordnung zu REST-URLs ist einfach. Weitere Informationen finden Sie im Abschnitt "Standardmethoden".

Eine Sammlung ist eine spezielle Art von Ressource, die eine Liste von Unterressourcen des gleichen Typs enthält. Ein Verzeichnis ist beispielsweise eine Sammlung von Dateiressourcen. Die Ressourcen-ID für eine Sammlung wird als Sammlungs-ID bezeichnet.

Ressourcennamen werden mit durch Schrägstriche getrennten Sammlungs-IDs und Ressourcen-IDs hierarchisch angeordnet. Wenn eine Ressource eine Unterressource enthält, wird der Name der Unterressource aus dem übergeordneten Ressourcennamen gefolgt von der ID der Unterressource gebildet. Auch hier erfolgt die Trennung durch Schrägstriche.

Beispiel 1: Ein Speicherdienst hat eine Sammlung von buckets, wobei jeder Bucket eine Sammlung von objects hat:

API-Dienstname	Sammlungs-ID	Ressourcen-ID	Sammlungs-ID	Ressourcen-ID
//storage.googleapis.com	/buckets	/bucket-id	/objects	/object-id

Beispiel 2: Ein E-Mail-Dienst hat eine Sammlung von users. Jeder dieser Nutzer hat die Unterressource settings und die Unterressource settings enthält eine Reihe weiterer Unterressourcen wie customFrom:

API-Dienstname	Sammlungs-ID	Ressourcen-ID	Ressourcen-ID	Ressourcen-ID
//mail.googleapis.com	/users	/[e-mail]	/settings	/customFrom

API-Ersteller können für Ressourcen- und Sammlungs-IDs einen beliebigen akzeptablen Wert auswählen, solange dieser innerhalb der Ressourcenhierarchie eindeutig ist. Weitere Richtlinien zur Auswahl geeigneter Ressourcen- und Sammlungs-IDs finden Sie unten.

Durch Aufteilen des Ressourcennamens, z. B. name.split("/")[n], können die einzelnen Sammlungs- und Ressourcen-IDs abgerufen werden, vorausgesetzt, keines der Segmente enthält einen Schrägstrich.

Vollständiger Ressourcenname

Ein schemaloser URI, der aus einem DNS-kompatiblen API-Dienstnamen und einem Ressourcenpfad besteht. Der Ressourcenpfad wird auch als relativer Ressourcenname bezeichnet. Beispiel:

"//library.googleapis.com/shelves/shelf1/books/book2"

Mit dem API-Dienstnamen lokalisiert der Client den Endpunkt des API-Dienstes. Es kann ein Pseudo-DNS-Name sein, der rein für interne Dienste verwendet wird. Wenn der API-Dienstname aus dem Kontext ersichtlich ist, werden häufig relative Ressourcennamen verwendet.

Relativer Ressourcenname

Ein URI-Pfad (path-noscheme) ohne das führende "/". Er identifiziert eine Ressource innerhalb des API-Dienstes. Beispiel:

"shelves/shelf1/books/book2"

Ressourcen-ID

Eine Ressourcen-ID besteht normalerweise aus einem oder mehreren nicht leeren URI-Segmenten (segment-nz-nc), die wie im vorangegangenen Beispiel die Ressource innerhalb der übergeordneten Ressource identifizieren. Die nicht nachvollziehbare Ressourcen-ID in einem Ressourcennamen muss genau ein URL-Segment haben, während die nachgestellte Ressourcen-ID in einem Ressourcennamen mehr als ein URI-Segment haben kann. Beispiel:

Sammlungs-ID	Ressourcen-ID
files	source/py/parser.py

API-Dienste sollten nach Möglichkeit URL-freundliche Ressourcen-IDs verwenden. Ressourcen-IDs müssen klar dokumentiert werden, unabhängig davon, ob sie vom Client, vom Server oder von beiden zugewiesen wurden. Beispielsweise werden Dateinamen normalerweise von Clients und E-Mail-Nachrichten-IDs von Servern zugewiesen.

Sammlungs-ID

Ein nicht leeres URI-Segment (segment-nz-nc), das wie in den oben angegebenen Beispielen die Sammlungsressource innerhalb der übergeordneten Ressource identifiziert.

Da Sammlungs-IDs häufig in den generierten Clientbibliotheken vorkommen, müssen sie die folgenden Anforderungen erfüllen:

• Sie müssen gültige C/C++ Kennungen sein.
• Sie müssen im Plural in Camel-Case-Schreibweise mit kleinem Anfangsbuchstaben angegeben sein. Wenn der Begriff keine geeignete Pluralform hat, zum Beispiel "Beweismittel" oder "Wetter", sollte die Singularform verwendet werden.
• Sie müssen klare und präzise englische Begriffe verwenden.
• Zu allgemeine Begriffe sollten vermieden oder entsprechend spezifiziert werden. Beispiel: rowValues wird values bevorzugt. Die folgenden Begriffe sollten ohne entsprechende Spezifizierung vermieden werden:
  • elements
  • entries
  • instances
  • items
  • objects
  • resources
  • types
  • values

Ressourcenname oder URL

Obgleich vollständige Ressourcennamen normalen URLs ähneln, sind sie nicht das Gleiche. Eine einzelne Ressource kann durch verschiedene API-Versionen, API-Protokolle oder API-Netzwerkendpunkte angegeben werden. Diese Informationen sind im vollständigen Ressourcennamen nicht angegeben. Dieser muss daher einer bestimmten API-Version und einem bestimmten API-Protokoll zugeordnet werden, um tatsächlich verwendet werden zu können.

Um einen vollständigen Ressourcennamen über REST APIs zu verwenden, muss dieser in eine REST-URL konvertiert werden. Dem Dienstnamen wird zu diesem Zweck das HTTPS-Schema vorangestellt und vor dem Ressourcenpfad die API-Hauptversion hinzugefügt. Außerdem müssen für den Ressourcenpfad Escapezeichen gesetzt werden, damit er nicht als URL behandelt wird. Beispiel:

// 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"

Ressourcenname als String

Google APIs müssen Ressourcennamen als einfache Strings darstellen, sofern dies nicht die Abwärtskompatibilität beeinträchtigt. Ressourcennamen sollten wie normale Dateipfade gehandhabt werden. Wenn ein Ressourcenname zwischen verschiedenen Komponenten übergeben wird, muss er als unteilbarer Wert behandelt werden und darf keine Datenverluste aufweisen.

Bei Ressourcendefinitionen sollte das erste Feld ein Zeichenfolgenfeld für den Ressourcennamen sein und sollte name heißen.

Hinweis: In den folgenden Codebeispielen wird die gRPC-Transcodierungssyntax verwendet. Folgen Sie dem Link, um Genaueres zu erfahren.

Beispiel:

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;
}

Hinweis: Um die Konsistenz von Ressourcennamen zu gewährleisten, darf der vorangestellte Schrägstrich nicht durch eine URL-Vorlagenvariable erfasst werden. Beispielsweise muss die URL-Vorlage "/v1/{name=shelves/*/books/*}" anstelle von "/v1{name=/shelves/*/books/*}" verwendet werden.

Fragen

F: Warum kann eine Ressource nicht mit Ressourcen-IDs identifiziert werden?

In großen Systemen gibt es zahlreiche Arten von Ressourcen. Um Ressourcen-IDs zum Identifizieren einer Ressource zu verwenden, verwenden wir ein ressourcenspezifisches Tupel, um eine Ressource zu identifizieren, z. B. (bucket, object) oder (user, album, photo). Dies führt zu mehreren größeren Problemen:

• Entwickler müssen die anonymen Tupel verstehen und sich merken.
• Tupels lassen sich generell schwieriger übergeben als Strings.
• Zentralisierte Infrastrukturen wie etwa Logging- oder Zugriffssteuerungssysteme, verstehen spezielle Tupel nicht.
• Spezielle Tupel schränken die Designflexibilität von APIs ein, wie etwa das Bereitstellen wiederverwendbarer API-Schnittstellen. Lang andauernde Vorgänge sind beispielsweise mit zahlreichen anderen API-Schnittstellen kompatibel, da sie flexible Ressourcennamen verwenden.

F: Warum heißt das Feld "Ressourcenname" name statt id?

Das Feld mit dem Ressourcennamen ist nach dem Konzept der Ressource "Name" benannt. Das Konzept name sorgt bei Entwicklern in der Regel jedoch für Verwirrung. Bezieht sich der Dateiname tatsächlich nur auf den Namen oder den vollständigen Pfad? Durch das Reservieren des Standardfelds name sind Entwickler gezwungen, einen spezifischeren Namen wie display_name, title oder full_name zu verwenden.

F: Wie sollte ich Ressourcennamen generieren und parsen?

Ressourcennamen verhalten sich wie Dateipfade. Sie können printf() verwenden, um Ressourcennamen aus Ressourcen-IDs zu generieren. Mit split() können Sie Ressourcennamen in Ressourcen-IDs parsen. Beachten Sie, dass einige nachgestellte Ressourcen-IDs mehrere URI-Segmente haben, die durch / getrennt sind, z. B. Dateipfad.