Posted by 山崎富美 / Developer Relations Team

[先日「東北地方太平洋沖地震を受けて」というブログ記事でご紹介した Google Person Finder ですが、API のドキュメンテーションを翻訳して欲しいとのご要望を頂いたのを受けて、ソフトウェアエンジニアの花岡 俊行が翻訳をしてくれました。なお、正式版の翻訳については code site に掲載されるのをお待ちください-山崎]

●Google Person Finder Data API documentation

How to download or upload data using the Person Finder API.
Person Finder API を使ったデータのダウンロード・アップロード方法

The Person Finder application stores and exports records using the People Finder Interchange Format (PFIF), which is based on XML. Documentation on the format is available here:
Person Finder アプリケーションはレコードを People Finder Interchange Format (PFIF) で保存、エクスポートします。PFIF は XML ベースのフォーマットです。PFIF に関するドキュメントは以下より参照できます。

PFIF 1.2 specification
PFIF 1.2 example document
PFIF FAQ and implementation guidelines


●Downloading data from Person Finder
Person Finder からデータをダウンロードする方法

To download data from Person Finder, you need an authorization token. You can request one by filling out this form
Person Finder からデータをダウンロードするには、authorization token が必要です。authorization token はこちらのフォームから申し込むことができます。

PFIF 1.2 person and note feeds are available here:
PFIF 1.2 person feed と note feed はここからアクセスできます。


https://subdomain.person-finder.appspot.com/feeds/person?key=auth_token
https://subdomain.person-finder.appspot.com/feeds/note?key=auth_token

By default, these feeds return the most recently added person records or note records in reverse chronological order. These query parameters are supported:
デフォルトでは、これらの feed は最も最近に追加された person レコードや note レコードを日付順に新しいものから返します。以下の query パラメータがサポートされています。

  • max_results: Return up to the specified number of results (maximum 200).
  • max_results: 指定された数を上限として結果を返します。(指定できる上限は 200)
  • skip: Skip the specified number of records before returning the next max_results results.
  • skip: 次の|max_results|個の結果を返す前に、指定された数の結果をスキップします。
  • min_entry_date: Return only results with an entry_date greater than or equal to the specified timestamp, which should be in UTC in yyyy-mm-ddThh:mm:ssZ format. If this parameter is specified, results will be returned in forward chronological order.
  • min_entry_date:指定された日付以降のタイムスタンプの entry_gate を持つ結果のみを返します。 タイムスタンプは UTC で yyyy-mm-ddThh:mm:ssZ のフォーマットで指定します。このパラメータが指定された場合、結果は日付順に古いものから返します。
  • person_record_id: Return only notes for this person record. This parameter is only valid for the note feed.
  • person_record_id: note feed のみで有効なパラメータです。指定された person record に対する notes のみ返します。

You can use the person_record_id parameter to subscribe to a feed of notes on a specific person.
person_record_id パラメータは 特定の人に対する note feed を subscribe するのに使えます。

If you need to keep another database synchronized with the Google Person Finder database, you can use the min_entry_date and skipparameters to download incremental updates. Use the latest entry_date you have previously received from Google Person Finder as themin_entry_date for your first request. Then take the latest entry_date in the batch you receive, and use it as the min_entry_date for your next request. Use the skip parameter to skip the records you already received that have the same entry_date. This algorithm is implemented bytools/download_feed.py.
Google Person Finder データベースと同期した他のデータベースが必要な場合、min_entry_date と skip パラメータを使って更新の増加分をダウンロードすることができます。最後に Google Person Finder から受け取った entry_date を、最初のリクエストの min_entry_date として用いてください。そしてそのリクエストの結果得られた中で最新の entry_date を、さらに次のリクエストの min_entry_date に用います。skip パラメータは既に得られた、同じ entry_date を持つ record をスキップするのに使うことができます。このアルゴリズムは tools/download_feed.py で実装されています。

If you know the PFIF person_record_id of a specific person, you can fetch a single PFIF person record with notes at the following URL:
特定の人の PFIF person_record_id がわかっている場合、notes 付きの単一の PFIF person record を次の URL から得ることができます。


https://subdomain.person-finder.appspot.com/api/read?key=auth_token&id=person_record_id

●Using the Person Finder Search API
Person Finder Search API を使う方法

To use the Person Finder Search API, you need an authorization token. You can request one by filling out this form
Person Finder Search API を使うには、authorization token が必要です。authorization token はこのフォームより申し込むことができます。

You can access the search API here:
search API はここからアクセスできます：


https://person-finder.appspot.com/api/search?key=auth_token&subdomain=subdomain&q=your query 

It will return the matching results as a XML file with PFIF format.
これにより、合致した結果を PFIF フォーマットの XML ファイルで返します。

●Uploading data into Person Finder
Person Finder にデータをアップロードする方法


You can also push one or more PFIF records to the Person Finder by posting an XML file to the following URL:
ひとつまたは複数の PFIF record を Person Finder にアップロードすることができます。アップロードは次の URL に XML ファイルを post することによって行えます。

https://subdomain.person-finder.appspot.com/api/write?key=auth_token


Both PFIF 1.1 and 1.2 are accepted. To obtain an auth_token, please contact pf-authkey@google.com. You will need to tell them which PFIF source domain you will be using the token for, and the token can only be used to upload person records whose person_record_id is prefixed with that domain.
PFIF 1.1, 1.2 の両方が受理されます。auth_token を得るには、pf-authkey@google.com に連絡してください。どの PFIF source domain に対して authorization token を使うかを明記する必要があります。authorization token は、その domain を prefix にもつ person_record_id の person record のアップロードのみに使うことができます。

Once you have prepared an XML file, you can use the following command to upload it:
XML ファイルが用意できたら、次のコマンドでアップロードすることができます。

curl -X POST -H 'Content-type: application/xml' --data-binary @your_file.xml \     https://subdomain.person-finder.appspot.com/api/write?key=auth_token


The XML document can contain elements with nested elements. To understand the proper XML format, see the PFIF example document. We recommend that you upload a single record or a small number of records as a test, retrieve the records using the Individual Person Record API (/api/read), and view the records on the site to verify that the results are what you expected. Pay careful attention to the handling of accented letters, note text, source URLs, and photo URLs (if you have them).
XML ドキュメントは、ネストされた 要素を持つことができます。厳密な XML フォーマットについての詳細は、PFIF example document を参照してください。まずテストとして、単一か少数の record をアップロードし、その結果を individual Person Record API (/api/read) を使って record を検索し、結果が予想通りになっているかどうかを確かめてみることをお勧めします。アクセント付き文字、note 文字列、source URL、photo URL を使っている場合は、特に注意を払ってください。 

Due to the size limitation on POST requests, you should split up files into batches of 100 elements. If you encounter an error, or need to correct problems in a previous upload, it is safe to upload the same records again. Records will replace existing records with the sameperson_record_id or note_record_id.
POST リクエストのサイズ制限により、ファイルを 100 要素ごとに分割する必要があります。エラーが発生した場合、または以前のアップロードを訂正する必要がある場合、同じ record をもう一度送っても問題ありません。同一の person_record_id か note_record_id を持つ record は上書きされます。

The response will be an XML document like this:
response は次のような XML document になるでしょう： 



<?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>



Each <status:write> element describes one batch of writes. <status:record_type> is the type of the batch. <status:parsed> says how many XML records were successfully parsed. <status:written> says how many were written to the datastore. In the above example, 1 person and 1 note were successfully written. When there are problems it will look like this:
それぞれの <status:write> 要素はひとつの書き込みバッチ操作を表しています。<status:record_type> はバッチ操作の種類です。<status:parsed> はいくつの XML record が正しくパースできたかを記述しています。<status:written> はいくつの record がデータストアに書き込まれたか記述しています。上の例では 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>

Each entry describes the reason why a particular record was skipped, and includes the record ID if one was given.
それぞれのエントリはあるレコードがなぜスキップされたか記述しており、record ID が指定されていればそれを含みます。 

When you upload person or note records, you will be replacing any existing records with the same record ID. It should be safe to upload the same data multiple times while you fix formatting problems.
person record や note record をアップロードした場合、同一の record ID をもつ record はすべて上書きされます。フォーマット問題を修正するために同一のデータを複数回アップロードすることは安全に行えます。