Skip to content

DataAPIJapanese

Jump to bottom
Hiroshi Ichikawa edited this page Jan 8, 2021 · 4 revisions

以下は Person Finder DataAPI の日本語訳です。

パーソンファインダーはXMLに基づいた People Finder Interchange Format (PFIF)を用いてレコードの保存および書き出しを行うアプリケーションです。


既存のパーソンファインダー・リポジトリにアクセスするには

既存のGoogleパーソンファインダーのリポジトリ内を検索、またデータのダウンロードやアップロードを行うにはAPIキーが必要です。注:これは自分で作製したインスタンスには必要ありません。大規模な災害に備え、Googleが管理・提供しているリポジトリにのみ必要となります。

  • アプリケーションを開発している方は、"test"リポジトリにAPIキー 43HxMWGBijFaYEr5 でアクセスできます。 このキーで書き込みを行う場合は、レコードIDのプレフィックスとしてドメイン名 testkey.personfinder.google.org を使用してください。
  • 他のリポジトリにアクセスするには、こちらからAPIキーを申請してください。アクセスタイプには３つの種類があります。
    • 検索：検索クエリに基づいたデータの取得が可能になります
    • 読み取り：データベース上のすべてのレコードを取得できます
    • 書き込み：データベース上にレコードを追加できます

トークンの申請を受けると、Googleは申請理由や、申請された利用方法によりユーザーにとってのパーソンファインダーの使いやすさや利便性を十分に拡張するものか、などを審査します。Googleはいかなる理由であれトークンの申請の許可および拒否を独自に決定する権利を有します。トークンを申請される方は パーソンファインダーAPI使用規約（英語） に合意しなければなりません。


パーソンファインダーからデータをダウンロードするには

PFIF1.4 person と note のフィードは以下URLからご覧になれます

https://www.google.org/personfinder/repository/feeds/person?key=api_key
https://www.google.org/personfinder/repository/feeds/note?key=api_key

初期設定では、これらの登録されたpersonおよびnoteのフィードは新しいものから古いものに逆日付順に表示します。以下のクエリパラメータに対応しています。

  • max_results: 最大200までの特定数のレコードを表示します。
  • skip: max_resultsの結果を表示する前に指定した数のレコードをスキップします。
  • min_entry_date: yyyy-mm-ddThh:mm:ssZ の形式で指定された協定世界時(UTC)におけるタイムスタンプよりも新しいあるいは同時刻の結果のみを表示します。このパラメータが指定された場合は表示順は日付順となります。
  • person_record_id: 指定された個人へのnoteだけを表示する。このパラメータはnoteフィードでのみ有効です。

person_record_id パラメータを用いて特定個人のnoteフィードを購読することが出来ます。

Googleパーソンファインダー・データベースと同期したデータベースが必要な場合は、min_entry_dateとskipパラメータを用いて差分のアップデートをダウンロードすることが出来ます。その際、前回Googleパーソンファインダーから取得した中で最も新しいentry_dateを、最初のリクエストのmin_entry_dateとして使ってください。次に、受け取ったbatchの中で最も新しいentry_dateを、次のリクエスト時にmin_entry_dateとして使ってください。同じentry_dateを持つ、すでに受け取ったレコードをスキップするためにもしskipパラメータを使ってください。このアルゴリズムはtools/download_feed.pyに実装されています。

特定個人のPFIF person_record_id がわかっている場合は、その個人レコードおよびnoteを以下のURLから取得できます。

https://www.google.org/personfinder/repository/api/read?key=api_key&id=person_record_id

APIを通してアクセスされたコンテンツをユーザーに表示する場合、その特定のレコードに関する調査の際に、オリジナルのソースを参照できるようにするために、必ずオリジナルのソースへのリンクを含めてください。また、APIを通してアクセスされたコンテンツと他のコンテンツを混ぜ、どのコンテンツがどのソースから来たのかを不明確にすることは避けてください。


パーソンファインダー検索APIを使うには

検索APIへは以下からアクセスできます:

https://www.google.org/personfinder/repository/api/search?key=api_key&q=your query

合致結果はPFIFフォーマットのXMLファイルとして表示されます。初期設定では最大１００件のレコードを取得できます。max_results パラメータを用いることで表示数を制限することが出来ます。

APIを通して取得したコンテンツをユーザーに表示する場合は、必ずオリジナルレコードへのリンクを含めてください。これはユーザがそのレコードに関してさらに調べる際に、オリジナルの記録を参照できるようにするためです。また、APIを通して取得したコンテンツと他のコンテンツをソースが不明確になるような形で混ぜて表示することは許可されません。


パーソンファインダーにデータをアップロードするには

XMLファイルを以下のURLにPOSTすることでパーソンファインダーに複数のPFIFレコードを追加することが出来ます。


https://www.google.org/personfinder/repository/api/write?key=api_key

PFIF1.1, 1.2, 1.3, 1.4 (例)が使用可能です。注:

  • APIキーが必要です(キーを取得する方法については、上の節を参照してください)。
  • person_record_id と note_record_id は domain_name/unique_string の形式である必要があります(例: example.com/113 )。domain_name はAPIキー申請フォームで"Domain Name"の欄に書いたものと同一である必要があります。"test"リポジトリを使う場合は testkey.personfinder.google.org を使用してください。

XMLファイルの準備が整ったら、以下のコマンドでアップロードしてください。

curl -X POST -H 'Content-type: application/xml' --data-binary @your_file.xml \     https://www.google.org/personfinder/repository/api/write?key=auth_token

XMLドキュメントは<pfif:person>エレメントを複数含むことができ、個々の<pfif:person>エレメントは<pfif:note>エレメントを複数含むことができます。このXMLフォーマットの詳細については、PFIF参考ドキュメントを参照して下さい。我々が推奨する方法は、まず一つ、もしくは少数のレコードをテストとしてアップロードし、Individual Person Record API (/api/read)を使ってそのデータを取得します。そしてサイトのレコードと自分の予測した結果が同じかどうかを確かめてみてください。アクセント記号付き文字、noteのテキスト、ソースURL、写真URLを含んでいる場合は特に注意してください。

POSTリクエストのサイズ制限によって、ファイルを100個の<pfif:person>エレメントごとに分割しなくてはならない場合があります。エラーの場合、もしくは前回のアップロードで修正すべきことがある場合は、同じレコードをもう一度アップロードするのがよいでしょう。そのレコードは同一のperson_record_idやnote_record_idを持った既存のレコードを置き換えます。

レスポンスは以下のようなXMLドキュメントになるはずです：

<?xml version="1.0"?>

<status:status>

  <status:write>

    <status:record_type>pfif:person</status:record_type>

    <status:parsed>1</status:parsed>

    <status:written>1</status:written>

    <status:skipped>

    </status:skipped>

  </status:write>



  <status:write>

    <status:record_type>pfif:note</status:record_type>

    <status:parsed>1</status:parsed>

    <status:written>1</status:written>

    <status:skipped>

    </status:skipped>

  </status:write>

</status:status>

1つの <status:write>エレメントが１回の書き込みに対応します。<status:record_type>は書き込みのタイプ、<status:parsed>はパースに成功したレコード数、そして<status:written>は datastore に書き込まれた数を表しています。上の例からは1人のpersonと1つのnoteの書き込みに成功したことが分かります。問題があった場合は以下のように表示されます：

<?xml version="1.0"?>

<status:status>

  <status:write>

    <status:record_type>pfif:person</status:record_type>

    <status:parsed>1</status:parsed>

    <status:written>0</status:written>

    <status:skipped>

      <pfif:person_record_id>google.com/person.4040</pfif:person_record_id>

      <status:error>not in authorized domain: u'google.com/person.4040'</status:error>

    </status:skipped>

  </status:write>



  <status:write>

    <status:record_type>pfif:note</status:record_type>

    <status:parsed>1</status:parsed>

    <status:written>0</status:written>

    <status:skipped>

      <pfif:note_record_id>zesty.ca/note.53</pfif:note_record_id>

      <status:error>ValueError: bad datetime: u'xyz'</status:error>

    </status:skipped>

  </status:write>

</status:status>

<status:skipped>の各項は、なぜそのレコードがスキップされたのか、もしレコードIDがある場合はそれも含まれます。

personやnoteをアップロードする場合、同一レコードIDのレコードが既に存在すれば、新しいもので置き換えられます。ですから、フォーマットのエラーを修正するために複数回同じデータをアップロードしても問題ありません。

GoogleはGoogleパーソンファインダーおよびそのAPIを通して提出されたPFIFレコードをPFIF Data Expiry Mechanism に準拠して扱います。

Clone this wiki locally