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

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

Идентификаторы необходимо передавать в запросах к 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 — категория образов.

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

Некоторые ресурсы в 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;
 }

В поле database_name допускается использовать буквы, цифры, символ подчеркивания и дефис, но не более 63 символов.

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

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

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

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

В примере:

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

См. такжеСм. также

• Репозиторий API Yandex Cloud — ссылка на .proto-спецификации API;
• Документация Yandex Resource Manager — ссылка на раздел Иерархия ресурсов Yandex Cloud.