Network Working Group Request for Comments: 2696 Категория: Informational C. Weider, A. Herron, A. Anantha (Microsoft), T. Howes (Netscape) Сентябрь 1999 года
Этот документ содержит информацию для сообщества Интернет. В нём не определяется стандарт Интернет какого-либо рода. Ограничений на распространение этого документа не накладывается.
Copyright (C) The Internet Society (1999). Все права защищены.
В данном документе описывается элемент управления, расширяющий функционал LDAPv3, для простого разбиения на страницы результатов поиска. Это расширение в виде элемента управления позволяет клиенту контролировать скорость, с которой LDAP-сервер возвращает результаты операции поиска LDAP. Этот элемент управления может быть полезен, когда ресурсы клиента LDAP ограничены и он не может обработать полный набор результатов от конкретного запроса LDAP, либо когда клиент LDAP подключается по низкоскоростному соединению. Другие операции над результирующим набором данных не определяются в данном расширении. Оно не предназначено для обеспечения более сложного управления результирующим набором данных.
Ключевые слова "MUST" (необходимо), "SHOULD" (следует) и "MAY" (возможно) в данном документе должны интерпретироваться так, как описано в BCP 14 [RFC2119].
Данный элемент управления включается в сообщения searchRequest и searchResultDone как часть поля controls конструкции LDAPMessage, как определено в разделе 4.1.12 стандарта LDAPv3. Структура элемента управления:
pagedResultsControl ::= SEQUENCE {
controlType 1.2.840.113556.1.4.319,
criticality BOOLEAN DEFAULT FALSE,
controlValue searchControlValue
}
Значение searchControlValue представляет собой строку октетов (OCTET STRING), в которой находится закодированная в BER версия следующей последовательности (SEQUENCE):
realSearchControlValue ::= SEQUENCE {
size INTEGER (0..maxInt),
-- запрашиваемый размер страницы (от клиента)
-- оценка размера результирующего набора данных (от сервера)
cookie OCTET STRING
}
Приложение-клиент LDAP, которому необходимо контролировать скорость возврата результатов, может (MAY) указать в запросе searchRequest элемент управления pagedResultsControl, в котором в поле size задан желаемый размер страницы, а в поле cookie указана строка нулевой длины. Задаваемый размер страницы может (MAY) быть больше нуля и меньше значения sizeLimit, определяемого в данном запросе searchRequest.
Если размер страницы больше или равен значению sizeLimit, серверу следует проигнорировать элемент управления, поскольку такой запрос может вернуть результаты в виде одной страницы. Если сервер не поддерживает данный элемент управления, он должен (MUST) вернуть ошибку unsupportedCriticalExtension в случае, если этот элемент управления помечен клиентом как критичный; в противном случае серверу следует (SHOULD) проигнорировать этот элемент управления. Далее в этом разделе подразумевается, что сервер не проигнорировал установленный клиентом элемент управления pagedResultsControl.
Каждый раз, когда сервер возвращает клиенту набор результатов при обработке поискового запроса, содержащего элемент управления pagedResultsControl, он включает элемент управления pagedResultsControl в сообщение searchResultDone. В возвращаемом клиенту элементе управления в поле size может (MAY) быть задано число, отражающее оценку сервером общего количества записей во всём результирующем наборе данных. Серверы, которые не могут обеспечить подобную оценку, могут задать поле size в ноль (0). В поле cookie должно (MUST) быть задано пустое значение, если больше нет записей для возвращения клиенту (то есть данная страница результатов поиска была последней), либо, если ещё имеются записи для возвращения клиенту, в это поле помещается какая-либо строка октетов (на выбор сервера), используемая для продолжения данного поиска.
Клиент должен (MUST) рассматривать данное куки как непрозрачную структуру и не делать никаких предположений о его внутренней организации или значении. Когда клиент захочет получить больше записей для конкретного результирующего набора данных, он должен (MUST) отправить серверу запрос searchRequest, все значения которого идентичны первоначальному запросу, за исключением значений полей messageID, cookie и, опционально, модифицированного значения поля size. Значением поля cookie должна (MUST) быть строка октетов, которую сервер вернул в последнем ответе searchResultDone. Поведение сервера при возврате куки из предыдущих ответов searchResultDone (за исключением последнего) не определено, поскольку реализация сервера может запрещать повторное использование куки.
После этого сервер вернёт очередной набор результатов из всего результирующего набора данных. Такое взаимодействие будет продолжаться до тех пор, пока клиент не получит все результаты (в этом случае куки в соответствующем поле сообщения searchResultDone будет пустым), либо пока клиент не откажется от выполнения данной последовательности поиска (как описано ниже). После завершения данной последовательности поиска куки перестаёт быть действительным и больше не должно (MUST NOT) быть использовано.
Клиент может отказаться от последовательности постраничных запросов поиска путём посылки поискового запроса, содержащего элемент управления pagedResultsControl в котором поле size установлено в ноль (0), а в поле cookie установлено последнее возвращённое сервером куки. Клиент может (MAY) использовать операцию LDAP Abandon для отказа от выполнения одного (текущего) постраничного запроса поиска, но это может привести к ошибке, поскольку таким образом клиентское куки может (MAY) оказаться недействительным.
Если по какой-либо причине сервер не может продолжить выполнять запрошенную клиентом операцию постраничного поиска, ему следует (SHOULD) вернуть соответствующую ошибку в сообщении searchResultDone. Если такое произошло, и клиенту и серверу следует считать, что набор постраничных результатов закрыт и больше не может быть возобновлён.
У клиента может быть произвольное количество ожидающих завершения поисковых запросов, в любом из которых может использоваться элемент управления pagedResultsControl. Реализации сервера, которые накладывают ограничение на количество незавершённых постраничных поисковых запросов от конкретного клиента, могут (MAY) либо вернуть ошибку unwillingToPerform при попытке этого клиента создать новый постраничный поисковый запрос, либо считать просроченным более старый набор результатов постраничного поиска. Если реализация сервера считает просроченным какой-либо предыдущий постраничный поисковый запрос, ей следует (SHOULD) вернуть ошибку unwillingToPerform при попытке клиента продолжить этот просроченный постраничный поиск.
Клиент может с уверенностью полагать, что все записи, удовлетворяющие заданному поисковому запросу, возвращаются один раз и только один раз за время последовательности запросов/ответов постраничного поиска, необходимых для полного перечисления результирующего набора данных, если только результирующий набор данных для этого запроса не был изменён с момента посылки сообщения searchRequest, с которого началась обработка данной последовательности запросов/ответов. В последнем случае клиент может получить какую-либо запись несколько раз, либо не получить всех записей, удовлетворяющих заданным критериям поиска.
Следующий пример иллюстрирует взаимодействие между клиентом и сервером, когда клиент выполняет поисковый запрос с размером страницы, ограниченным до 3 записей. Полный возвращаемый сервером результирующий набор данных содержит 5 записей.
В строках, начинающихся с "К:", показаны запросы, отправляемые от клиента серверу. В строках, начинающихся с "С:", показаны ответы, отправляемые от сервера клиенту. В строках, начинающихся с "--", даны комментарии, разъясняющие пример.
-- Клиент посылает поисковый запрос, запрашивая постраничный вывод результатов -- с размером страницы 3. К: SearchRequest + pagedResultsControl(3,"") -- Сервер отвечает тремя записями, плюс указание того, что всего в результате -- поиска найдено 5 записей, а также непрозрачным куки, который клиент -- должен будет использовать для получения последующих страниц. С: SearchResultEntry С: SearchResultEntry С: SearchResultEntry С: SearchResultDone + pagedResultsControl(5, "opaque") -- Клиент посылает идентичный поисковый запрос (за исключением messageID), -- возвращая то же непрозрачное куки, тем самым запрашивая следующую страницу. К: SearchRequest + PagedResultsControl(3, "opaque") -- Сервер отвечает двумя записями, плюс указание того, что больше записей -- нет (пустое куки). С: SearchResultEntry С: SearchResultEntry С: SearchResultDone + pagedResultsControl(5,"")
Для серверов LDAP, предоставляющих интерфейс к каталогам X.500 (93), элемент управления постраничным выводом результатов (определённый в этом документе) может быть напрямую отображён в запрос X.500 (93) PagedResultsRequest (определённый в X.511 [x500]). Параметр size может быть отображён в pageSize. Параметр cookie может быть отображён в queryReference. Поля sortKeys и reverse запроса X.500 PagedResultsRequest исключаются.
Разработчики сервера должны учитывать ресурсы, используемые при работе с клиентами, отправляющими запросы с использованием элемента управления простого постраничного вывода, чтобы обеспечить такой режим работы, при котором неправильное использование клиентом этого элемента управления не блокирует другие легитимные операции.
Реализации серверов могут принудительно переопределять ограничения по размеру для предотвращения извлечения больших частей общедоступного каталога.
С помощью данного элемента управления клиенты могут определять, насколько много записей соответствуют конкретному фильтру, перед тем, как эти записи будут возвращены данному клиенту. Для реализации такого поведения может потребоваться специальная обработка запросов на тех серверах, которые выполняют проверку контроля доступа к записям для определения того, может ли наличие конкретной записи быть раскрыто клиенту.
[LDAPv3] Wahl, M., Howes, T. и S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, декабрь 1997 г.
[Bradner97] Bradner, S., "Ключевые слова для обозначения уровня требований в RFC", BCP 14, RFC 2119, март 1997 г.
Chris Weider
Microsoft Corp., 1 Microsoft way, Redmond, WA 98052, USA
Телефон: +1 425 882-8080
EMail: cweider@microsoft.com
Andy Herron
Microsoft Corp., 1 Microsoft way, Redmond, WA 98052, USA
Телефон: +1 425 882-8080
EMail: andyhe@microsoft.com
Anoop Anantha
Microsoft Corp., 1 Microsoft way, Redmond, WA 98052, USA
Телефон: +1 425 882-8080
EMail: anoopa@microsoft.com
Tim Howes
Netscape Communications Corp., 501 E. Middlefield Road, Mountain View, CA 94043, USA
Телефон: +1 415 937-2600
EMail: howes@netscape.com
Copyright (C) Internet Society (1999). Все права защищены.
Этот документ и его переводы могут быть скопированы и переработаны в другие документы. Производные работы, комментирующие или иным способом поясняющие данный документ, либо оказывающие помощь в его реализации, могут быть подготовлены, скопированы, опубликованы и распространены, целиком или частями, без каких-либо ограничений, при условии, что указанное выше уведомление об авторском праве и этот параграф будут включены во все такие копии и производные работы. Однако, в этот документ как таковой не может быть внесено каких-либо изменений, таких как удаление уведомления об авторских правах или ссылок на Internet Society или другие организации Интернет, за исключением случаев, когда это требуется для разработки стандартов Интернет (при этом должны быть пройдены процедуры получения авторских прав, определённые в стандартах Интернет), либо когда это требуется при переводе на языки, отличные от английского.
Предоставляемые выше ограниченные права являются бессрочными и не подлежат отзыву Internet Society, его наследниками или правопреемниками.
Этот документ и содержащаяся в нём информация распространяются "КАК ЕСТЬ" и INTERNET SOCIETY И INTERNET ENGINEERING TASK FORCE ОТКАЗЫВАЮТСЯ ОТ ВСЕХ ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, ПОМИМО ПРОЧЕГО, ЛЮБЫЕ ГАРАНТИИ ТОГО, ЧТО ИСПОЛЬЗОВАНИЕ ПРИВЕДЁННОЙ ЗДЕСЬ ИНФОРМАЦИИ НЕ НАРУШАЕТ КАКИХ-ЛИБО ПРАВ ИЛИ ЛЮБЫЕ ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ ПРИГОДНОСТИ ДЛЯ КОНКРЕТНЫХ ЦЕЛЕЙ.
Финансирование функций RFC Editor в настоящий момент обеспечивается Internet Society.