Open Archives Initiative メタデータ・ハーベスティング・プロトコル実装ガイドライン

- ハーベスタ実装者向けガイドライン

プロトコルバージョン 2.0 （2002-06-14）
ドキュメントバージョン（2002/06/09T16:43:00Z）
http://www.openarchives.org/OAI/2.0/guidelines-harvester.htm

編集者

OAI 役員 :
Carl Lagoze <lagoze@cs.cornell.edu> -- コーネル大学 - コンピュータサイエンス
 Herbert Van de Sompel <herbertv@lanl.gov> -- ロスアラモス国立研究所 - 研究図書館

OAI 技術委員会委員 :
Michael Nelson <m.l.nelson@larc.nasa.gov> -- NASA - ラングレー研究センタ
 Simeon Warner <simeon@cs.cornell.edu> -- コーネル大学 - コンピュータサイエンス

本ドキュメントは、 Open Archives Initiative メタデータ・ハーベスティング・プロトコル (OAI-PMH) の付録『実装ガイドライン』の一部です。

1. はじめに

本ドキュメントは、ハーベスタの実装者および保守管理者向けガイドラインです。 OAI-PMH は、レポジトリを実装しやすいように設計されているため、それだけハーベスタへの負荷が大きくなっています。たとえば、リポジトリが日付スタンプの単位について日または秒のどちらかを選択できるようにするため、ハーベスタはその両方の単位をサポートする必要があります (must)。

2. ハーベスティング・ソフトウェアの使用

OAI-PMH ハーベスタはロボットエージェントで、リポジトリへのサービス不能攻撃が発生しないよう注意する必要があります
(should)。 web ロボットの取り扱いに不慣れな実装者やオペレータの方は、詳細について Web ロボットページを参照してください
(should)。新しいハーベスティング・ソフトウェアのテストや新規インストールを行う場合は、予想外の応答やエラー条件により矢継ぎ早の再試行が引き起こされることのないように必ずチェックを行います (should)。HTTPステータスコード 403 やその他の予想外の応答を受け取った場合、ハーベスティング・ソフトウェアが（手動操作の間）終了するようにプログラムします (should)。

OAI-PMH の、リポジトリとのインタフェースは、自動ハーベスティング・ソフトウェアでアクセスするように作られているため、 /robots.txt 基準によってハーベスティングの許可または禁止を決定することは通常ありません。ハーベスタがこのファイルを参照するとは考えられていません。

2.1 エージェントと連絡先情報

OAI-PMH ハーベスタは、HTTP ロボットエージェントの標準規約に準拠するものとし、なかでも HTTP User-Agent および From ヘッダの提供をしっかり行うようにします (should)。 User-Agent ヘッダフィールドには、要求を発信したユーザエージェントについての情報が含まれるようにします (should)。これについては、HTTP 仕様書のセクション 14.43 をご覧ください。 From ヘッダフィールドには、ハーベスティングされたデータを管理する人のインターネット電子メールアドレスが入ります (should)。これについては、HTTP 仕様書のセクション 14.22 をご覧ください。 From ヘッダに含まれる電子メールアドレスは、ハーベスタが問題を引き起こした場合の連絡先となります。

3. 日付スタンプと単位

リポジトリの各レコードには日付スタンプがありますが、これは GetRecord、ListIdentifiers、ListRecords の各応答の header ブロックに含まれています。日付スタンプは個々のレコードのものであり、特定のアイテムから抽出されたすべてのレコード（メタデータフォーマット）の日付スタンプが同じになるとは限りません (may not)。

リポジトリでは、日付スタンプの表記は日または秒の単位のどちらかで構いません (may) が、必ずサポートされている最も細かい単位を Identify 応答の <granularity> 要素の中で宣言します (must)。

どのリポジトリでも必ず YYYY-MM-DD、YYYY-MM、YYYY というフォームの from と until のパラメータがサポートされている (must) ため、ハーベスタに日またはもっと粗い単位でハーベスティングをさせる場合、 <granularity> 応答を考慮する必要はありません (may not)。なお、日付変更時刻は午前零時 (00:00h) UTC であり、 from と until のパラメータの単位に関わらず、 datestamp 値はリポジトリがサポートしている本来の（最も細かい）単位で返されます。

ハーベスタに日より細かい単位でハーベスティングをさせる場合、 Identify 応答の <granularity> 要素を調べる必要があります (must)。サポートしている単位よりも細かい単位で from と until のパラメータを発行すると、リポジトリは badGranularity エラーとなります。

リポジトリ内のアイテムは、同じ datestamp (すなわち日付スタンプが YYYY-MM-DD なら同じ日) の範囲内であれば、ハーベスティング中またはハーベスティング後に変更や追加ができます (may)。したがって、リポジトリから増分ハーベスティングを行うには、ハーベスタによる次のハーベスティングを　datestamp の増分 (単位が YYYY-MM-DD なら1日) だけ重複するようにします (should)。また、ハーベスティング中に生じる変化が応答に反映されるかどうかはリポジトリの実装に依存するので、次の増分ハーベスティングの from の引数はシーケンスの応答リスト前半部にある responseDate の戻り値で決定します。 datestamp 単位が1秒のリポジトリからハーベスティングを行う場合、レポートされた responseDate とリポジトリで要求に答える必要のある検索が実行された時間との差分だけ重複させることを推奨します。

4. セット

ハーベスタでは、リスト要求の set パラメータを指定せずに、また、返されたレコードの <setSpec> 要素を無視して、リポジトリが抽出するセットを無効にしても構いません (may)。

リポジトリにセットが実装されているか、あるいは、リポジトリにどのセットが実装されているかを判断するため、ハーベスタから ListSets 要求が発行されます (should)。エラー応答 noSetHierarchy は、セットがサポートされていないという意味です。サポートされていれば、実装されたセットのリストが返されます。

なお、setSpec 値のコロン (:) は階層を表します。サブセットをもつセットからハーベスティングを行うと、リポジトリによって、指定されたセットに含まれるすべてのアイテムのメタデータとともに、そのセットのサブセットにあるすべてのアイテムのメタデータも再帰的に返されます。たとえば、あるリポジトリから item1 の SetSpec エントリ aaa:bbb が返された場合、セット aaa のハーベスティングを行うと、その応答には item1 のメタデータが返されます（「OAI-PMH: 2.7 セット」参照）。

5. フローコントロール、ロードバランシング、転送

ハーベスティング・ソフトウェアを、リポジトリからのフローコントロール応答に従わせることは重要です。そうしないと、ハーベスティングの試行がリポジトリへのサービス不能攻撃に変わる場合があります (may)。

フローコントロールの方法として 503 Service Unavailable HTTP 応答を発行するリポジトリには、 Retry-After HTTP ヘッダを加え、ハーベスタが次の要求を発行するまでの待機時間を指示します (should)。ハーベスタが Retry-After ヘッダのない 503 応答を受けた場合、相当の時間（分）を待たずに、できれば行うことが望ましい手動操作の間もなく、自動的に再試行が行われないようにします
(should not)。ハーベスタが無制限に試行を繰り返すようなプログラムにしてはなりません (must not)。

ロードバランシング方針の一部として、あるいは別の理由から、リポジトリが 302 Found HTTP 応答が発行して、ハーベスタを Location HTTP ヘッダに記載された別の URL に転送させても構いません。ハーベスタが Location ヘッダのない 302 応答を受けた場合、要求が自動的に再試行されないようにします。

6. 不完全リストと `resumptionToken`

ハーベスタには常に、ListIdentifiers、 ListRecords、ListSets の各要求に対する不完全リスト応答を受け取ることができる必要があります (must)。応答に resumptionToken 要素が含まれていれば、不完全リスト応答であると分かります。次の不完全リスト要求は、resumptionToken 要素の内容を除外対象の resumptionToken 引数値として行われます。最後の不完全リスト要求は、resumptionToken 要素に内容がありません。要求と応答のシーケンスの例を以下に示します。

Original list request:

  http://an.oai.org/script?
    verb=ListIdentifiers&from=2001-01-01&until=2001-01-03

First incomplete list response:

<L ...>
  <header>...</header>
  <header>...</header>
  ...
  <resumptionToken completeListSize="20" 
    cursor="0">2001-01-02:2001-01-03:0</resumptionToken>
</ListIdentifiers>

Request for second incomplete list:

  http://an.oai.org/script?
    verb=ListIdentifiers&resumptionToken=2001-01-02%3A2001-01-03%3A0

Second incomplete list response:

<ListIdentfiers...>
  <header>...</header>
  <header>...</header>
  ...
  <resumptionToken completeListSize="20"
    cursor="9">2001-01-03:2001-01-03:0</resumptionToken>
</ListIdentifiers>

Request for third incomplete list:

  http://an.oai.org/script?
    verb=ListIdentifiers&resumptionToken=2001-01-03%3A2001-01-03%3A0

Third incomplete list response, the empty resumptionToken indicates that this request and response completes the list request sequence:

<ListIdentfiers...>
  <header>...</header>
  <header>...</header>
  ...
  <resumptionToken completeListSize="20" 
    cursor="18"></resumptionToken>
</ListIdentifiers>

The complete list may now be created by concatenating the contents of all the incomplete lists.

6.1 URL の resumptionToken 引数をコード化する

ハーベスタで前の要求の resumptionToken 値を使用して次の要求を行う場合、その値は必ず HTTP GET と POST の要求のために正しくコード化します (must)。予約文字と正しいエスケープシーケンスについては、「OAI-PMH: 3.1.1.3 OAI-PMH 要求のキーワード引数の特殊文字をコード化する」をご覧ください。

6.2 リスト要求のエラーリカバリ

ネットワークエラーなどにより、不完全リスト応答が消失するような状況が生じた場合、ハーベスタは直近の resumptionToken を再発行し、リスト要求シーケンスを続行することができます。直近の不完全リスト要求実施を再現・続行する要件は、リスト要求シーケンスに対する応答が，全体として正しい完全リスト応答となるようにすることです。

ハーベスタが不完全リスト要求シーケンスの実行中に badResumptionToken エラーを受け取った場合、resumptionToken が期限切れであるかまたは別の理由で正しくないと考えねばなりません。この場合、リスト要求シーケンスを再開させる方法はありません。ハーベスタは最初からリスト要求をやり直す必要があります。

ハーベスタがその他のエラーを受け取った場合，リスト要求シーケンスに回復不能な問題が生じています。ハーベスタは最初からリスト要求をやり直す必要があります。

7. 応答圧縮

リポジトリが圧縮をサポートしている場合、Identify 応答にcompression 要素を含めることで、この旨を知らせるようにします
(should)。ハーベスタで圧縮を使用する場合、どの圧縮を要求するか決定するために圧縮要素を探すことができます。以下の例は Identify の抜粋です。

<Identify ...>
  ...
  <compression>gzip</compression>
  <compression>compress</compression>
  ...
</Identify>

上の例は、このレポジトリでは必須の identity コード化とともに、gzip と compress のコード化がサポートされていることを示しています。

この応答を受け取ったハーベスタが gzip 圧縮をサポートしていれば、以下のような HTTP ヘッダの付いた要求を発行することも考えられます (might)。

Accept-Encoding: gzip, identity

Accept-Encoding: gzip;q=1.0, identity;q=0.5

なお、identity は必ずリストに含まれます (must)。最初のフォームは、両タイプの応答が受け入れ可能であることを示しているだけですが、2番目のフォームは gzip コード化が優先する（ q 値が大きい）ことを示しています。2番目のフォームを推奨します（「HTTP: RFC 2616 セクション "14.3 Accept-Encoding"」および「OAI-PMH: 3.1.3 応答圧縮」参照）。

8. リポジトリからすべてのメタデータをハーベスティングする

プロキシやアグリゲータ、その他のエージェントが、セット構造やあらゆるメタデータフォーマットも含め、レポジトリの完全なコピーをハーベスティングしようとする場合も考えられます (may)。これを行うには以下の方法があります。

Identify 要求を発行して、サポートされる最も高精度な日付スタンプの単位を確認します。
ListMetadataFormats 要求を発行して、サポートされたすべての metadataPrefixes リストを取得します。
サポートされた metadataPrefix ごとに ListRecords 要求を使用してハーベスティングを行います。日より細かい単位がサポートされている場合、日付スタンプの単位が分かれば重複を減らすことができます。
セット構造は、返された各レコードの header ブロックの setSpec 要素から推測することができます（整合性チェックが可能）。
アイテムを、その構成レコードから再構成しても構いません。ハーベストしたアイテムには，ローカルの日付スタンプを割り当てる必要があります。
<about> ブロックに含まれる出所その他の情報は、ハーベスティングされたメタデータフォーマットですべて同じであれば、アイテムレベルで組み立て直しても構いません。ただし、この情報は各メタデータフォーマットに対し，個々に供給することが考えられるため、場合によってはメタデータフォーマットごとに分けて格納しておく必要があります。

謝辞

OAI-PMH の策定およびその他の Open Archives Initiative の活動に対して、デジタル図書館連盟とネットワーク情報連合、そして全米科学財団（Grant No. IIS-9817416）からご協力をいただきました。 OAI-PMH バージョン 2.0 の策定で多大なご協力をいただいた個人の皆様に、プロトコルドキュメントにおいて感謝の意を表します。

ドキュメント履歴

2002-06-14: OAI-PMH バージョン 2.0 のリリースに合わせて本ドキュメントをリリース