[要約] RFC 2696は、LDAPサーバーからの結果をページ単位で取得するための制御拡張です。目的は、大量の結果を効率的に処理するために、クライアントが必要なページのみを取得できるようにすることです。
Network Working Group C. Weider
Request for Comments: 2696 A. Herron
Category: Informational A. Anantha
Microsoft
T. Howes
Netscape
September 1999
LDAP Control Extension for Simple Paged Results Manipulation
Status of this Memo
このメモの位置付け
This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited.
このメモはインターネットコミュニティのための情報を提供します。それはどんな種類のインターネット標準を指定しません。このメモの配布は無制限です。
Copyright Notice
著作権表示
Copyright (C) The Internet Society (1999). All Rights Reserved.
著作権（C）インターネット協会（1999）。全著作権所有。
This document describes an LDAPv3 control extension for simple paging of search results. This control extension allows a client to control the rate at which an LDAP server returns the results of an LDAP search operation. This control may be useful when the LDAP client has limited resources and may not be able to process the entire result set from a given LDAP query, or when the LDAP client is connected over a low-bandwidth connection. Other operations on the result set are not defined in this extension. This extension is not designed to provide more sophisticated result set management.
この文書では、検索結果の簡単なページングのためのLDAPv3制御拡張機能について説明します。この制御拡張機能は、クライアントがLDAPサーバがLDAP検索操作の結果を返す速度を制御することができます。このコントロールは、LDAPクライアントは、リソースが限られていたときに有用である可能性があり、与えられたLDAPクエリからの結果セット全体を処理することができないかもしれない、またはLDAPクライアントは、低帯域幅接続を介して接続されている場合。結果セット上の他の操作は、この拡張で定義されていません。この拡張は、より洗練された結果セットの管理を提供するように設計されていません。
The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [bradner97].
キーワード「MUST」、「SHOULD」、および本書で使用される「MAY」は[bradner97]で説明されるように解釈されるべきです。
This control is included in the searchRequest and searchResultDone messages as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The structure of this control is as follows:
【のLDAPv3]のセクション4.1.12で定義されるように、この制御は、たLDAPMessageの制御フィールドの一部としてsearchRequestとsearchResultDoneメッセージに含まれています。次のようにこのコントロールの構造は次のとおりです。
pagedResultsControl ::= SEQUENCE {
controlType 1.2.840.113556.1.4.319,
criticality BOOLEAN DEFAULT FALSE,
controlValue searchControlValue
}
The searchControlValue is an OCTET STRING wrapping the BER-encoded version of the following SEQUENCE:
searchControlValueは、以下の配列のBER符号化されたバージョンをラップオクテット列です。
realSearchControlValue ::= SEQUENCE {
size INTEGER (0..maxInt),
-- requested page size from client
-- result set size estimate from server
cookie OCTET STRING
}
An LDAP client application that needs to control the rate at which results are returned MAY specify on the searchRequest a pagedResultsControl with size set to the desired page size and cookie set to the zero-length string. The page size specified MAY be greater than zero and less than the sizeLimit value specified in the searchRequest.
結果はsearchRequestに長さゼロの文字列に設定された所望のページサイズとクッキーに設定されたサイズとpagedResultsControlを指定するかもしれ返される速度を制御する必要があるLDAPクライアントアプリケーション。指定したページサイズがゼロより大きく、searchRequestで指定SIZELIMIT値未満とすることができます。
If the page size is greater than or equal to the sizeLimit value, the server should ignore the control as the request can be satisfied in a single page. If the server does not support this control, the server MUST return an error of unsupportedCriticalExtension if the client requested it as critical, otherwise the server SHOULD ignore the control. The remainder of this section assumes the server does not ignore the client's pagedResultsControl.
ページ・サイズがより大きいかSIZELIMIT値に等しい場合、要求は、単一ページで満足させることができるように、サーバは、制御を無視すべきです。サーバはこのコントロールをサポートしていない場合は、クライアントが重要としてそれを要求した場合、サーバは、そうでない場合は、サーバーが制御を無視すべきである、unsupportedCriticalExtensionのエラーを返さなければなりません。このセクションの残りの部分は、サーバーがクライアントのpagedResultsControlを無視しません想定しています。
Each time the server returns a set of results to the client when processing a search request containing the pagedResultsControl, the server includes the pagedResultsControl control in the searchResultDone message. In the control returned to the client, the size MAY be set to the server's estimate of the total number of entries in the entire result set. Servers that cannot provide such an estimate MAY set this size to zero (0). The cookie MUST be set to an empty value if there are no more entries to return (i.e., the page of search results returned was the last), or, if there are more entries to return, to an octet string of the server's choosing,used to resume the search.
pagedResultsControlを含む検索要求を処理するときに、サーバがクライアントに結果セットを返すたびに、サーバはsearchResultDoneメッセージ内pagedResultsControlコントロールを含みます。クライアントに返さ制御では、サイズが全体の結果セット内のエントリの合計数のサーバーの見積もりに設定されるかもしれません。そのような推定値がゼロ（0）には、このサイズを設定してもよい提供することができないサーバー。返すために多くのエントリがある場合クッキーは、サーバの選んだのオクテット文字列に、戻るにはこれ以上のエントリが存在しない場合（つまり、検索結果のページが最後に返された）空の値に設定するか、しなければなりません検索を再開するために使用されます。
The client MUST consider the cookie to be an opaque structure and make no assumptions about its internal organization or value. When the client wants to retrieve more entries for the result set, it MUST send to the server a searchRequest with all values identical to the initial request with the exception of the messageID, the cookie, and optionally a modified pageSize. The cookie MUST be the octet string on the last searchResultDone response returned by the server. Returning cookies from previous searchResultDone responses besides the last one is undefined, as the server implementation may restrict cookies from being reused.
クライアントは、不透明な構造であることと、その内部組織や値についての仮定をしないためにクッキーを考慮する必要があります。クライアントが結果セットのためのより多くのエントリを検索したい場合は、サーバーにメッセージIDを除き、クッキー、および必要に応じて変更されたpageSizeとの最初のリクエストと同一のすべての値を持つsearchRequestを送らなければなりません。クッキーは、サーバによって返された最後のsearchResultDone応答のオクテット文字列でなければなりません。サーバの実装が再利用されることからクッキーを制限することができるよう、最後の1以外にも、以前のsearchResultDone応答からクッキーを返すことは、未定義です。
The server will then return the next set of results from the whole result set. This interaction will continue until the client has retrieved all the results, in which case the cookie in the searchResultDone field will be empty, or until the client abandons the search sequence as described below. Once the paged search sequence has been completed, the cookie is no longer valid and MUST NOT be used.
その後、サーバは、全体の結果セットから次の結果セットを返します。クライアントがsearchResultDoneフィールドのクッキーが空になり、その場合、すべての結果を、検索したまで、または以下に説明するように、クライアントは、検索順序を放棄するまで、この相互作用は継続されます。ページング検索シーケンスが完了すると、クッキーは、もはや有効ではないため、使用しないでください。
A sequence of paged search requests is abandoned by the client sending a search request containing a pagedResultsControl with the size set to zero (0) and the cookie set to the last cookie returned by the server. A client MAY use the LDAP Abandon operation to abandon one paged search request in progress, but this is discouraged as it MAY invalidate the client's cookie.
ページングされた検索要求のシーケンスは、ゼロ（0）に設定されたサイズと、サーバによって返された最後のクッキーに設定されたCookieをpagedResultsControlを含む検索要求を送信するクライアントによって破棄されます。クライアントは、進行中のページング検索要求を放棄する操作を放棄LDAPを使用することができるが、これは、クライアントのクッキーを無効にする可能性があるとして推奨されません。
If, for any reason, the server cannot resume a paged search operation for a client, then it SHOULD return the appropriate error in a searchResultDone entry. If this occurs, both client and server should assume the paged result set is closed and no longer resumable.
、何らかの理由で、サーバーがクライアントのためのページング検索操作を再開することができない場合、それはsearchResultDoneエントリに適切なエラーを返すべきです。この問題が発生した場合、クライアントとサーバーの両方がページング結果セットが閉じられ、もはや再開可能ではないと仮定しなければなりません。
A client may have any number of outstanding search requests pending, any of which may have used the pagedResultsControl. A server implementation which requires a limit on the number of outstanding paged search requests from a given client MAY either return unwillingToPerform when the client attempts to create a new paged search request, or age out an older result set. If the server implementation ages out an older paged search request, it SHOULD return "unwilling to perform" if the client attempts to resume the paged search that was aged out.
クライアントはpagedResultsControlを使用した可能性のあるそれらの保留中の優れた検索要求、任意の数を有することができます。クライアントが新しいページングされた検索要求、または年齢アウト古い結果セットを作成しようとしたときに特定のクライアントからの優秀なページングされた検索要求の数の制限を必要とするサーバーの実装はunwillingToPerformを返してもよいのいずれか。古いページング検索要求アウトサーバの実装の年齢ならば、それは、クライアントがエージングアウトされたページング検索を再開しようとすると、「実行するために不本意」返すべきです。
A client may safely assume that all entries that satisfy a given search query are returned once and only once during the set of paged search requests/responses necessary to enumerate the entire result set, unless the result set for that query has changed since the searchRequest starting the request/response sequence was processed. In that case, the client may receive a given entry multiple times and/or may not receive all entries matching the given search criteria.
そのクエリの結果セットがsearchRequest開始以降に変更された場合を除き、クライアントは安全に指定した検索クエリを満たすすべてのエントリは、結果セット全体を列挙するために必要なページングされた検索要求/応答のセットの間に一度だけ返されていることを仮定してもよいです要求/応答シーケンスが処理されました。その場合、クライアントは、指定されたエントリを複数回受けることができる、および/または指定した検索条件に一致するすべてのエントリを受信できない場合があります。
The following example illustrates the client-server interaction between a client doing a search requesting a page size limit of 3. The entire result set returned by the server contains 5 entries.
次の例では、サーバから返された結果セット全体が5つのエントリが含まれている3のページサイズの制限を要求して検索を実行し、クライアントの間で、クライアントとサーバの対話を示しています。
Lines beginning with "C:" indicate requests sent from client to server. Lines beginning with "S:" indicate responses sent from server to client. Lines beginning with "--" are comments to help explain the example.
始まる行「C：」は、クライアントからサーバに送信された要求を示しています。始まる行「S：」は、サーバーからクライアントに送信された応答を示しています。 「 - 」で始まる行は一例を説明するコメントです。
-- Client sends a search request asking for paged results -- with a page size of 3. C: SearchRequest + pagedResultsControl(3,"") -- Server responds with three entries plus an indication -- of 5 total entries in the search result and an opaque -- cooking to be used by the client when retrieving subsequent -- pages. S: SearchResultEntry S: SearchResultEntry S: SearchResultEntry S: SearchResultDone + pagedResultsControl(5, "opaque") -- Client sends an identical search request (except for -- message id), returning the opaque cooking, asking for -- the next page. C: SearchRequest + PagedResultsControl(3, "opaque") -- Server responds with two entries plus an indication -- that there are no more entries (null cookie). S: SearchResultEntry S: SearchResultEntry S: SearchResultDone + pagedResultsControl(5,"")
SearchRequest + pagedResultsControl（3、「」） - サーバーは、3つのエントリプラス表示で応答 - 5つの合計エントリの検索に： - 3 Cのページサイズと - クライアントは、ページング結果を求めて検索要求を送信します結果と不透明 - ページ - それ以降の取得時に、クライアントによって使用されるように調理します。 S：SのSearchResultEntry：のSearchResultEntry S：SのSearchResultEntry：SearchResultDone + pagedResultsControl（5、 "不透明"） - 次のページ - を求めて、不透明な料理を返す、 - クライアントは（メッセージIDを除く）、同一の検索要求を送信します。 C：SearchRequest + PagedResultsControlは（3、「不透明」） - サーバーは、2つのエントリに加えて表示して応答します - これ以上のエントリ（nullのクッキー）があること。 S：のSearchResultEntry S：のSearchResultEntry S：SearchResultDone + pagedResultsControl（5、 ""）
For LDAP servers providing a front end to X.500 (93) directories, the paged results control defined in this document may be mapped directly onto the X.500 (93) PagedResultsRequest defined in X.511 [x500]. The size parameter may be mapped onto pageSize. The cookie parameter may be mapped onto queryReference. The sortKeys and reverse fields in the X.500 PagedResultsRequest are excluded.
X.500のフロントエンド（93）ディレクトリを提供するLDAPサーバーの場合、本文書で定義されたページング結果制御はX.511 [X500]で定義されたX.500（93）PagedResultsRequest上に直接マッピングすることができます。サイズパラメータは、pageSizeを上にマッピングすることができます。クッキーパラメータはqueryReferenceにマッピングされてもよいです。 X.500 PagedResultsRequestでSORTKEYSと逆のフィールドは除外されています。
Server implementors should consider the resources used when clients send searches with the simple paged control, to ensure that a client's misuse of this control does not lock out other legitimate operations.
クライアントは、単純なページング制御で検索を送信するときにサーバーの実装は、このコントロールのクライアントの誤用は、他の正当な操作をロックアウトしないことを保証するために、使用するリソースを検討すべきです。
Servers implementations may enforce an overriding sizelimit, to prevent the retrieval of large portions of a publically-accessible directory.
サーバの実装は、公にアクセス可能なディレクトリの大部分の検索を防止するために、オーバーライドいるsizelimitを適用してもよいです。
Clients can, using this control, determine how many entries match a particular filter, before the entries are returned to the client. This may require special processing in servers which perform access control checks on entries to determine whether the existence of the entry can be disclosed to the client.
クライアントは、このコントロールを使用して、エントリがクライアントに返される前に、特定のフィルタに一致するエントリの数を決定することができます。これは、エントリの存在がクライアントに開示することができるかどうかを判断するためにエントリにアクセス制御チェックを行うサーバで特別な処理が必要な場合があります。
[LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.
【のLDAPv3]ワール、M.、ハウズ、T.およびS. Kille、 "軽量のディレクトリアクセスプロトコル（V3）"、RFC 2251、1997年12月。
[Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[Bradner97]ブラドナーの、S.、 "要件レベルを示すためにRFCsにおける使用のためのキーワード"、BCP 14、RFC 2119、1997年3月。
Chris Weider Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA
クリス・ウイダーマイクロソフト株式会社1マイクロソフト道、レッドモンド、WA 98052 USA
Phone: +1 425 882-8080 EMail: cweider@microsoft.com
電話：+1 425 882-8080 Eメール：cweider@microsoft.com
Andy Herron Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA
アンディー・ヘロンマイクロソフト社1マイクロソフト道、レッドモンド、WA 98052 USA
Phone: +1 425 882-8080 EMail: andyhe@microsoft.com
電話：+1 425 882-8080 Eメール：andyhe@microsoft.com
Anoop Anantha Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA
アヌープAnanthaマイクロソフト株式会社98052 USAの1マイクロソフトウェイレドモンド、
Phone: +1 425 882-8080 EMail: anoopa@microsoft.com
電話：+1 425 882-8080 Eメール：anoopa@microsoft.com
Tim Howes Netscape Communications Corp. 501 E. Middlefield Road Mountain View, CA 94043 USA
ティム・ハウズネットスケープコミュニケーションズ株式会社501 E.ミドルロード、マウンテンビュー、CA 94043 USA
Phone: +1 415 937-2600 EMail: howes@netscape.com
電話：+1 415 937-2600 Eメール：howes@netscape.com
Copyright (C) The Internet Society (1999). All Rights Reserved.
著作権（C）インターネット協会（1999）。全著作権所有。
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
この文書とその翻訳は、コピーして他の人に提供し、それ以外についてはコメントまたは派生物は、いかなる種類の制限もなく、全体的にまたは部分的に、準備コピーし、公表して配布することができることを説明したり、その実装を支援することができます、上記の著作権表示とこの段落は、すべてのそのようなコピーや派生物に含まれていることを条件とします。しかし、この文書自体は著作権のための手順はで定義されている場合には、インターネット標準を開発するために必要なものを除き、インターネットソサエティもしくは他のインターネット関連団体に著作権情報や参照を取り除くなど、どのような方法で変更されないかもしれませんインターネット標準化プロセスが続く、または英語以外の言語に翻訳するために、必要に応じなければなりません。
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.
上記の制限は永久で、インターネット学会やその後継者や譲渡者によって取り消されることはありません。
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
この文書とここに含まれている情報は、基礎とインターネットソサエティおよびインターネットエンジニアリングタスクフォースはすべての保証を否認し、明示または黙示、その情報の利用がない任意の保証を含むがこれらに限定されない「として、」上に設けられています特定の目的への権利または商品性または適合性の黙示の保証を侵害します。
Acknowledgement
謝辞
Funding for the RFC Editor function is currently provided by the Internet Society.
RFC Editor機能のための基金は現在、インターネット協会によって提供されます。