Стандартные методы

Статья создана

Обновлена 23 ноября 2023 г.

Get
List
Create
Update
Delete

Ниже перечислены стандартные методы API и соответствующие им HTTP-методы:

Метод API	HTTP-метод	Тело запроса	Тело ответа
Get	GET	—	Представление ресурса.
List	GET	—	Список ресурсов.
Create	POST	Представление ресурса.	Объект Operation.
Update	PATCH	Представление ресурса.	Объект Operation.
Delete	DELETE	—	Объект Operation.

Ниже приведены gRPC-описания стандартных методов и рассмотрены примеры соответствующих REST запросов.

Get

Возвращает представление запрашиваемого ресурса.

Методу соответствует HTTP-метод GET.

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

 rpc Get (GetDiskRequest) returns (Disk) {
   // Методу Get соответствует HTTP-метод GET.
   option (google.api.http) = {
     get: "/compute/v1/disks/{disk_id}"
   };
 }

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

Пример REST запроса на получение диска:

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

List

Выводит список ресурсов определенной категории. Например, список дисков или список виртуальных машин.

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

Методу List соответствует HTTP-метод GET. В параметрах запроса необходимо передать идентификатор родительского ресурса, например каталога.

Максимальное значение поля page_size равно 1000.

Метод List поддерживает постраничное отображение результатов.

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

 rpc List (ListDisksRequest) returns (ListDisksResponse) {
   // Методу List соответствует HTTP-метод GET.
   option (google.api.http) = {
     get: "/compute/v1/disks"
   };
 }
 message ListDisksRequest {
   // Идентификатор каталога, для которого
   // нужно получить список дисков.
   // Обязательное поле.
   string folder_id = 1;

   // Максимальное количество результатов на странице ответа.
   // Если число возвращаемых результатов
   // больше значения, заданного в page_size, сервис возвращает поле
   // [ListDisksResponse.next_page_token]. Используйте его
   // для получения следующей страницы.
   int64 page_size = 2;

   // Токен запрашиваемой страницы с результатами.
   // Чтобы получить следующую страницу,
   // подставьте в это поле значение из
   // [ListDisksResponse.next_page_token], которое было
   // получено в результате предыдущего запроса List.
   string page_token = 3;
 }

 message ListDisksResponse {
   // Список дисков.
   repeated Disk disks = 1;
   // Токен следующей страницы результатов.
   string next_page_token = 2;
 }

Пример получения списка дисков в REST:

GET https://compute.api.cloud.yandex.net/compute/v1/disks?folderId=a3s17h9sbq5asdgss12

Create

Создает ресурс в указанном облаке, каталоге, сети и т. д.

Методу Create соответствует HTTP-метод POST. В качестве параметров необходимо передать идентификатор родительского ресурса, в котором нужно создать ресурс (например, идентификатор каталога).

Метод Create имеет асинхронную сигнатуру. Он возвращает объект Operation, который содержит статус операции, а также идентификатор создаваемого ресурса.

В поле description допускается использовать не более 256 символов, в полях name и labels — не более 63 символов.

При попытке создать ресурс, который уже существует, метод вернет ошибку ALREADY_EXISTS. Подробнее об ошибках

Пример gRPC-описания метода Create для создания диска в заданном каталоге:

 rpc Create (CreateDiskRequest) returns (operation.Operation) {
   // Методу Create соответствует HTTP-метод POST.
   option (google.api.http) = {
     post: "/compute/v1/disks" body: "*"
   };
   // В поле `metadata` объекта Operation
   // содержится представление `CreateDiskMetadata`.
   // В случае успешного завершения операции
   // в поле `response` объекта Operation
   // содержится представление дискового ресурса.
   option (yandex.api.operation) = {
     metadata: "CreateDiskMetadata"
     response: "Disk"
   };
 }

 message CreateDiskRequest {
   // Идентификатор каталога, в котором нужно создать диск.
   // Обязательное поле.
   string folder_id = 1;

   // Имя диска.
   string name = 2;

   // Описание диска.
   string description = 3;

   // Метки диска в формате 'ключ: значение'.
   map<string, string> labels = 4;

   // Тип диска.
   string type_id = 5;

   // Идентификатор зоны, в которой нужно создать диск.
   string zone_id = 6;

   // Размер диска в байтах.
   int64 size = 7;

   oneof source {
     // Идентификатор образа, на основе которого нужно создать диск.
     string image_id = 8;

     // либо идентификатор снимка, с которого нужно создать диск.
     string snapshot_id = 9;
   }
 }

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

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

 POST https://compute.api.cloud.yandex.net/compute/v1/disks

 {
   "folderId": "a3s17h9sbq5asdgss12",
   "name": "disk-1",
   "description": "Test disk",
   "zoneId" : "ru-central1-a",
   "typeId" : "network-nvme",
   "size" : 10737418240
 }

При вызове метода Create, возвращаемый объект Operation будет содержать идентификатор создаваемого ресурса, даже если операция еще не была завершена. Используя этот идентификатор, вы можете обратиться к ресурсу через метод Get или List.

Update

Изменяет представление ресурса. Методу соответствует HTTP-метод PATCH.

Метод Update поддерживает частичное изменение ресурса. Поля, которые требуется изменить, указываются в запросе в поле update_mask (подробнее). Поля, которые не указаны в поле update_mask, не будут изменены. Если в запросе не передается update_mask, значения всех полей будут обновлены по следующему правилу:

для полей, указанных в запросе, будут использованы переданные значения;
значения остальных полей будут сброшены на значения по умолчанию.

Метод имеет асинхронную сигнатуру. Он возвращает объект Operation, который содержит статус операции и представление измененного ресурса.

В поле description допускается использовать не более 256 символов, в полях name и labels — не более 63 символов.

Пример gRPC-описания метода Update для изменения дискового ресурса:

 rpc Update (UpdateDiskRequest) returns (operation.Operation) {
   // Методу Update соответствует HTTP-метод PATCH.
   option (google.api.http) = {
     patch: "/compute/v1/disks/{disk_id}" body: "*"
   };
   // В поле `metadata` объекта Operation
   // содержится представление `UpdateDiskMetadata`.
   // В случае успешного завершения операции
   // в поле `response` объекта Operation
   // содержится представление измененного дискового ресурса.
   option (yandex.api.operation) = {
     metadata: "UpdateDiskMetadata"
     response: "Disk"
   };
 }
 message UpdateDiskRequest {
   // Идентификатор изменяемого диска.
   // Обязательное поле.
   string disk_id = 1;

   // Маска, задающая поля, которые нужно изменить.
   google.protobuf.FieldMask update_mask = 2;

   // Имя диска.
   string name = 3;

   // Описание диска.
   string description = 4;

   // Метки диска в формате 'ключ: значение'.
   map<string, string> labels = 5;

   // Размер диска в байтах.
   int64 size = 6;
 }

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

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

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

 {
   "name": "Новое имя",
   "description": "Новое описание",
   "size": "10737418240",
   "updateMask" : "name,description"
 }

В примере будут изменены только поля "name" и "description".

Delete

Удаляет заданный ресурс.

Методу Delete соответствует HTTP-метод DELETE. В параметрах запроса необходимо передать идентификатор ресурса, который требуется удалить.

Метод имеет асинхронную сигнатуру. Он возвращает объект Operation, который содержит статус операции удаления.

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

 rpc Delete (DeleteDiskRequest) returns (operation.Operation) {
   // Методу соответствует HTTP-метод DELETE.
   option (google.api.http) = {
     delete: "/compute/v1/disks/{disk_id}"
   };
   // В поле `metadata` объекта Operation
   // содержится представление `DeleteDiskMetadata`.
   // В случае успешного завершения операции
   // в поле `response` объекта Operation
   // содержится представление ресурса `google.protobuf.Empty`.
   option (yandex.api.operation) = {
     metadata: "DeleteDiskMetadata"
     response: "google.protobuf.Empty"
   };
 }
 message DeleteDiskRequest {
   // Идентификатор удаляемого диска.
   // Обязательное поле.
   string disk_id = 1;
 }

 message DeleteDiskMetadata {
   // Идентификатор удаляемого диска.
   string disk_id = 1;
 }

Пример REST запроса на удаление диска:

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

Стандартные методы

GetGet

ListList

CreateCreate

UpdateUpdate

DeleteDelete

Была ли статья полезна?

Get

List

Create

Update

Delete