Идентификация ресурсов

Каждый ресурс в API Яндекс.Облака имеет свой уникальный идентификатор. Идентификаторы генерируются на стороне сервиса и представляют собой строку, состоящую из символов латинского алфавита и цифр.

Идентификаторы необходимо передавать в запросах к API при обращении к ресурсам.

Пример gRPC-описания метода Get для получения диска:

 rpc Get (GetDiskRequest) returns (Disk) {
   option (google.api.http) = {
     get: "/compute/v1/disks/{disk_id}"
   };
 }

 message GetDiskRequest {
   // Идентификатор запрашиваемого диска.
   string disk_id = 1;
 }

В REST для каждого ресурса определен свой уникальный URL, который формируется по схеме:

https://<домен>/<сервис>/<версия API>/<категория ресурса>/<идентификатор ресурса>

Пример запроса диска в REST:

 GET https://compute.api.cloud.yandex.net/compute/v1/disks/e0m97h0gbq0foeuis03

Как видно из примера, URL ресурсов идентифицируется связкой категория ресурса и идентификатор ресурса.

Категория ресурса определяет тип ресурса. Например: disks — категория дисков; instances — категория виртуальных машин; images — категория образов.

Примечание

Не следует путать категорию ресурса с понятием коллекция в REST. Категории не являются самостоятельными ресурсами, и вы не можете управлять ими (создавать, изменять или запрашивать информацию). Категории носят служебный характер — они используются в URL ресурсов для маршрутизации запросов на стороне сервиса.

Идентификаторы вложенных ресурсов

Некоторые ресурсы в API являются вложенными, то есть создаются в контексте других ресурсов. Например, базы данных создаются в кластерах. При обращении к таким ресурсам всегда следует указывать два параметра:

  • Идентификатор родительского ресурса. В примере с базами данных родительским ресурсом является кластер.
  • Имя вложенного ресурса. В нашем примере вложенным ресурсом является база данных.

Имя вложенного ресурса задается пользователем и должно быть уникальным в рамках родительского ресурса. Например, в одном кластере не могут быть созданы две базы данных с одинаковыми именами.

Пример gRPC-описания метода Get для получения ресурса базы данных:

 rpc Get (GetDatabaseRequest) returns (Database) {
   option (google.api.http) = {
     get: "/managed-postgresql/v1/clusters/{cluster_id}/databases/{database_name}"
   };
 }
 message GetDatabaseRequest {
   // Идентификатор кластера, которому принадлежит база данных.
   // Обязательное поле.
   string cluster_id = 1;

   // Имя базы данных.
   // Обязательное поле.
   string database_name = 2;
 }

В REST уникальный URI вложенных ресурсов имеет иерархическую структуру:

/<категория родительского ресурса>/<идентификатор родительского ресурса>/<категория вложенного ресурса>/<идентификатор вложенного ресурса>

Пример REST запроса для получения базы данных:

 GET https://mdb.api.cloud.yandex.net/managed-postgresql/v1/clusters/24f17h0gfqf7oeuis2f/databases/db-testing

В примере:

  • clusters — категория родительского ресурса;
  • 24f17h0gfqf7oeuis2f — идентификатор родительского ресурса;
  • databases — категория вложенного ресурса;
  • db-testing — идентификатор вложенного ресурса.

См. также