В вычислениях метод PATCH - это метод запроса, поддерживаемый протоколом протокола передачи гипертекста (HTTP) для внесения частичных изменений в существующий ресурс. [1] Метод PATCH предоставляет объект, содержащий список изменений, которые должны быть применены к ресурсу, запрошенному с использованием унифицированного идентификатора ресурса HTTP (URI). [1] Список изменений предоставляется в виде документа PATCH. [1] Если запрошенный ресурс не существует, сервер может создать ресурс в зависимости от типа носителя документа PATCH и разрешений. [1]Изменения, описанные в документе PATCH, должны быть семантически четко определены, но могут иметь другой тип носителя, чем исправляемый ресурс. [2] Структуры, такие как XML , JSON, могут использоваться для описания изменений в документе PATCH.
История патча [ править ]
В соответствии с семантикой, определенной в протоколе HTTP , методы GET , PUT и POST должны использовать полное представление ресурса. Метод PUT, который можно использовать для создания или замены ресурса, идемпотентен и может использоваться только для полных обновлений. Формы редактирования, используемые в обычном приложении Ruby on Rails, должны создавать новые ресурсы, применяя частичные обновления к родительскому ресурсу. В связи с этим требованием в 2010 году в протокол HTTP был добавлен метод PATCH. [3] [4]
PUT vs PATCH vs POST [ править ]
HTTP - это основа передачи данных во всемирной паутине . Это протокол запроса-ответа , который помогает пользователям связываться с сервером для выполнения операций CRUD . HTTP поддерживает ряд методов запроса, таких как PUT , POST и PATCH, для создания или обновления ресурсов. [5]
Основное различие между методами PUT и PATCH заключается в том, что метод PUT использует URI запроса для предоставления измененной версии запрошенного ресурса, которая заменяет исходную версию ресурса, тогда как метод PATCH предоставляет набор инструкций для изменения ресурса. Если ЗАПЛАТА документ больше , чем размер новой версии ресурса , посланной PUT методом , то PUT , является предпочтительным методом. [1]
Метод POST можно использовать для отправки частичных обновлений ресурсу. Основное различие между методами POST и PATCH заключается в том, что метод POST может использоваться только тогда, когда он написан для поддержки приложений или приложений, поддерживающих его семантику, тогда как метод PATCH может использоваться обычным образом и не требует поддержки приложений. Если результат использования метода PATCH неизвестен, предпочтительнее использовать метод POST. [1] [6]
Ресурсы исправления [ править ]
Метод PATCH является атомарным . [1] Либо все изменения, указанные методом PATCH, применяются, либо сервером не применяется ни одно из изменений. [1] Есть много способов проверить, успешно ли был применен патч. Например, утилиту 'diff' можно применить к более старой и новой версии файла, чтобы найти различия между ними. [1]
Кешированный ответ PATCH считается устаревшим. Его можно использовать только для запросов GET и HEAD, которые могут следовать за запросом PATCH. [1]
Заголовки объекта в документе PATCH применимы только к документу PATCH и не могут быть применены к запрошенному ресурсу. [1]
Стандартного формата для документа PATCH не существует, и он различается для разных типов ресурсов. Сервер должен проверить, подходит ли полученный документ PATCH для запрошенного ресурса. [1]
Документ JSON Patch будет выглядеть так:
{ "op" : "add" , "variable" : "count" , "value" : 1 }«op» представляет операцию, выполняемую над ресурсом. «переменная» представляет изменяемый ресурс. «значение» представляет собой сумму, добавляемую к существующему ресурсу. [7] Перед применением изменений в документе PATCH сервер должен проверить, подходит ли полученный документ PATCH для запрошенного ресурса. Если запрос PATCH завершается успешно, он возвращает ответ 204 . [8]
Документ XML PATCH будет выглядеть так:
<add sel = "doc / user [@ email = 'xyz @ abc.com']" type = "@address" >ABC Road</add>Элемент <user> находится с помощью атрибута email. К элементу <user> добавлен новый атрибут «адрес» со значением «ABC Road». [9]
Пример [ править ]
Простой пример запроса PATCH
ПАТЧ /example.txt HTTP / 1.1 Хост: www.example.com Content-Type: приложение / пример Если совпадение : "c0b42b66e" Длина содержимого: 120
[изменения]
[changes] - это патч-документ, содержащий все изменения, которые необходимо внести в ресурс example.txt.
Успешный ответ PATCH на существующий текстовый файл:
HTTP / 1.1 204 Нет содержимого Расположение содержимого: /example.txt ETag : "c0b42b66f"
Ответ 204 означает, что запрос был успешно обработан. [10]
Компромиссы между PUT и PATCH [ править ]
Использование метода PUT требует большей пропускной способности по сравнению с методом PATCH, когда к ресурсу необходимо применить только несколько изменений. [ необходима цитата ] Но когда используется метод PATCH, он обычно включает выборку ресурса с сервера, сравнение исходного и нового файлов, создание и отправку файла сравнения. На стороне сервера сервер должен прочитать файл diff и внести изменения. Это связано с большими накладными расходами по сравнению с методом PUT. [11] С другой стороны, метод PUT требует, чтобы GET выполнялся перед PUT, и трудно гарантировать, что ресурс не изменяется между GET иPUT запросы.
Внимание [ править ]
Метод PATCH не является «безопасным» в смысле RFC 2616: он может изменять ресурсы, не обязательно ограничиваясь теми, которые упомянуты в URI . [1]
Метод PATCH не идемпотентен . Его можно сделать идемпотентным с помощью условного запроса. [1] Когда клиент делает условный запрос к ресурсу, запрос считается успешным только в том случае, если ресурс не обновлялся с момента последнего обращения клиента к этому ресурсу. Это также помогает предотвратить повреждение ресурса, поскольку некоторые обновления ресурса могут выполняться только с определенной базовой точки. [1]
Обработка ошибок [ править ]
Запрос PATCH может завершиться ошибкой при возникновении любой из следующих ошибок:
Документ исправления неправильного формата [ править ]
Сервер возвращает ответ 400 (неверный запрос), если документ PATCH отформатирован не так, как требуется. [1]
Неподдерживаемый патч-документ [ править ]
Сервер возвращает ответ 415 (неподдерживаемый тип носителя ) с заголовком ответа Accept-Patch, содержащим поддерживаемые типы носителя, когда клиент отправляет неподдерживаемый документ исправления. Это информирует клиента о том, что документ PATCH, отправленный клиентом, не может быть применен к запрошенному ресурсу. [1]
Необработанный запрос [ править ]
Сервер возвращает ответ 422 (Unprocessable Entity), когда сервер понимает документ PATCH, но не может изменить запрошенный ресурс либо потому, что это приводит к тому, что ресурс становится недействительным, либо приводит к другому состоянию ошибки. [1]
Ресурс не найден [ править ]
Сервер возвращает ответ 404 (Not Found), когда документ PATCH не может быть применен к несуществующему ресурсу. [1]
Конфликтующее состояние [ править ]
Сервер возвращает ответ 409 (конфликт), когда сервер не может применить исправление для текущего состояния ресурса. [1]
Противоречивая модификация [ править ]
Сервер возвращает ответ 412 (Precondition Failed), когда предварительное условие, предоставленное клиентом с использованием заголовка If-Match или If-Unmodified-Since, не выполняется. Если предварительное условие не указано и есть конфликтующая модификация, сервер возвращает ответ 409 (конфликт). [1]
Параллельное изменение [ править ]
Сервер возвращает ответ 409 (конфликт), если запросы PATCH к определенному ресурсу необходимо применить в определенном порядке, и сервер не может обрабатывать параллельные запросы PATCH. [1]
Соображения безопасности [ править ]
Запрос PATCH должен использовать такие механизмы, как условные запросы с использованием Etags и заголовок запроса If-Match, чтобы гарантировать, что данные не будут повреждены во время исправления. [1] В случае сбоя запроса PATCH или сбоя канала или тайм-аута, клиент может использовать запрос GET для проверки состояния ресурса. [1] Сервер должен гарантировать, что злонамеренные клиенты не используют метод PATCH для потребления чрезмерных ресурсов сервера. [1]
Ссылки [ править ]
- ^ a b c d e f g h i j k l m n o p q r s t u v w x y "Метод PATCH для HTTP" . Проверено 12 сентября 2015 . CS1 maint: обескураженный параметр ( ссылка )
- ^ "Не патч, как идиот" . Не патчитесь как идиот . Проверено 16 сентября 2015 года . CS1 maint: обескураженный параметр ( ссылка )
- ^ RFC 5789
- ^ "История PATCH" . weblog.rubyonrails.org . Проверено 25 сентября 2015 года . CS1 maint: обескураженный параметр ( ссылка )
- ^ «Протокол передачи гипертекста - HTTP / 1.1» . Проверено 13 сентября 2015 года . CS1 maint: обескураженный параметр ( ссылка )
- ^ «Почему PATCH хорош для вашего HTTP API» . Почему PATCH хорош для вашего HTTP API . Проверено 16 сентября 2015 года . CS1 maint: обескураженный параметр ( ссылка )
- ^ «Патч JSON - draft-ietf-appsawg-json-patch-08» . Проверено 13 сентября 2015 года . CS1 maint: обескураженный параметр ( ссылка )
- ^ "ПАТЧ" . Веб-документы MDN . Проверено 11 октября 2018 .
- ^ "XML RFC" . tools.ietf.org . Проверено 25 сентября 2015 года . CS1 maint: обескураженный параметр ( ссылка )
- ^ "ПАТЧ" . Веб-документы MDN . Проверено 12 октября 2018 .
- ^ Даррен. «Лучшие практики REST API 3: частичные обновления - PATCH против PUT» . www.blogger.com . Проверено 13 сентября 2015 года . CS1 maint: обескураженный параметр ( ссылка )
