メニュー
Amazon CloudSearch
開発者ガイド (API Version 2013-01-01)

Amazon CloudSearch 用にデータを準備

インデックス作成のための検索ドメインにアップロードする前に、JSON または XML 形式でデータを作成する必要があります。検索結果として返せるようにする各項目がドキュメントとして示されます。各ドキュメントには固有のドキュメント ID、および検索し、結果を返すデータを含むフィールドが 1 つ以上あります。このドキュメントフィールドを使用して、ドメイン用に設定したインデックスフィールドの値を入力します。詳細については、「configure indexing options」を参照してください。

Creating Document Batches」はデータの整形方法を説明しています。Amazon CloudSearch の JSON および XML スキーマの詳細については、「Document Service API」を参照してください。

Amazon CloudSearch でインデックスフィールドにドキュメントデータをマッピング

インデックスのフィールドに入力するために、Amazon CloudSearch は対応するドキュメントフィールドからデータを読み込みます。ドキュメントデータで指定されたフィールドはすべてインデックス作成オプションで設定する必要があります。ドキュメントはドメイン用に設定されたフィールドのサブセットを含むことができます。すべてのドキュメントが必ずしもすべてのフィールドを含む必要はありません。さらに、あるフィールドから別のフィールドにデータをコピーして、インデックスの追加フィールドに入力することもできます。これにより、フィールドに対して異なるオプションを設定することで、同一のソースデータを異なる方法で利用することができます。

text-array のような配列フィールドは、最大 1000 個の値を含むことができます。検索時に、これらの値のどれかが検索クエリに一致すると、ドキュメントはヒット項目として返されます。

Amazon CloudSearch でドキュメントバッチを作成

ドキュメントバッチを作成して、検索可能にするデータを記述します。ドキュメントバッチをドメインに送信すると、ドメインのインデックス作成オプションに従って自動的にデータのインデックスが作成されます。コマンドラインツールおよび Amazon CloudSearch コンソールは、各種ソースドキュメントから自動的にドキュメントバッチを生成できます。

ドキュメントバッチは追加および削除操作のコレクションであり、ドメインで追加、更新、削除するドキュメントを表します。バッチは JSON または XML で記述できます。最大バッチサイズは 5 MB です。個々のドキュメントの最大サイズは 1 MB です。

可能な限り最高のアップロードパフォーマンスを実現するために、追加および削除オペレーションを最大バッチサイズに近いバッチにグループ化します。ドキュメントサービスに大量の単一ドキュメントバッチを送信すると、変更が検索結果に反映されるまでに要する時間が長くなります。アップロードするデータが大量にある場合は、バッチを並列して送信できます。使用できる同時アップローダーの数は、検索インスタンスタイプによって異なります。ドメインの必要なインスタンスタイプオプションを設定することで、一括アップロード用に事前スケーリングすることができます。詳細については、「スケーリングオプションの設定」を参照してください。

バッチ内のドキュメントごとに、以下を指定する必要があります。

  • 実行するオペレーション: add または delete

  • ドキュメントの一意の ID。ドキュメント ID では、任意の英字または数字と次の文字を使用できます。​_ - = # ; : / ? ドキュメント ID は、1​~​128 文字以内にする必要があります。

  • 各ドキュメントフィールドの名前と値のペア。latlon フィールドの値を指定するには、カンマ区切りリストとして緯度と経度を指定します。たとえば、"location_field": "35.628611,-120.694152" のようになります。ドキュメントを JSON で指定する場合、フィールドの値を null にすることはできません(ただしフィールドを完全に省略することはできます)。

たとえば、次の JSON バッチは、1 個のドキュメントを追加し、1 個のドキュメントを削除します。

Copy
[ {"type": "add", "id": "tt0484562", "fields": { "title": "The Seeker: The Dark Is Rising", "directors": "Cunningham, David L.", "genres": ["Adventure","Drama","Fantasy","Thriller"], "actors": ["McShane, Ian","Eccleston, Christopher","Conroy, Frances", "Crewson, Wendy","Ludwig, Alexander","Cosmo, James", "Warner, Amelia","Hickey, John Benjamin","Piddock, Jim", "Lockhart, Emma"] } }, {"type": "delete", "id": "tt0484575" } ]

XML 形式では同じバッチが次のようになります。

Copy
<batch> <add id="tt0484562"> <field name="title">The Seeker: The Dark Is Rising</field> <field name="directors">Cunningham, David L.</field> <field name="genres">Adventure</field> <field name="genres">Drama</field> <field name="genres">Fantasy</field> <field name="genres">Thriller</field> <field name="actors">McShane, Ian</field> <field name="actors">Eccleston, Christopher</field> <field name="actors">Conroy, Frances</field> <field name="actors">Ludwig, Alexander</field> <field name="actors">Crewson, Wendy</field> <field name="actors">Warner, Amelia</field> <field name="actors">Cosmo, James</field> <field name="actors">Hickey, John Benjamin</field> <field name="actors">Piddock, Jim</field> <field name="actors">Lockhart, Emma</field> </add> <delete id="tt0484575" /> </batch>

無効な JSON または XML を含むドキュメントバッチをアップロードすると、予想できない結果が生じます。エラーが発生すると処理が停止しますが、それ以前の追加および削除オペレーションはドメインに適用されます。JSON または XML データの妥当性は、xmllintjsonlint のようなツールを使用して確認できます。

JSON バッチと XML バッチにはどちらも、XML で有効な UTF-8 文字のみを含めることができます。有効な文字は、制御文字のタブ(0009)、復帰(000D)、改行(000A)、および Unicode と ISO/IEC 10646 での有効な文字です。FFFE、FFFF、サロゲートブロックの D800–DBFF と DC00–DFFF は無効で、エラーが発生します(詳細については、『Extensible Markup Language (XML) 1.0 (Fifth Edition)』 を参照してください)。無効な文字に一致する次の正規表現を使用して、無効な文字を削除することができます/[^\u0009\u000a\u000d\u0020-\uD7FF\uE000-\uFFFD]/

データを JSON 形式にする場合、フィールド値内の引用符(")およびバックスラッシュ(\)はバックスラッシュを使ってエスケープする必要があります。(例:

Copy
"title":"Where the Wild Things Are" "isbn":"0-06-025492-0" "image":"images\\covers\\Where_The_Wild_Things_Are_(book)_cover.jpg" "comment":"Sendak's \"Where the Wild Things Are\" is a children's classic."

データを XML 形式にする場合、フィールド値内のアンパサンド (&) および、不等号 (より小さい) (<) は、該当する実体参照 (&amp;&lt;) によって表現する必要があります。

(例:

Copy
<field name="title">Little Cow &amp; the Turtle</field> <field name="isbn">0-84466-4774</field> <field name="image">images\covers\Little_Cow_&amp;_the_Turtle.jpg</field> <field name="comment">&lt;insert comment></field>

ユーザー生成コンテンツの大きなブロックがある場合は、特殊な文字をすべて実体参照に置き換えるのではなく、フィールド全体を CDATA セクションで囲むこともできます。(例:

Copy
<field name="comment"><![CDATA[Monsters & mayhem--what's not to like! ]]>

Amazon CloudSearch でのドキュメントの追加および更新

追加オペレーションでは、インデックスに追加する新しいドキュメント、または、更新する既存のドキュメントを指定します。

ドキュメントを追加または更新するときは、ドキュメントの ID と、ドキュメントが含むすべてのフィールドを指定します。すべてのドキュメントで、すべての設定されたフィールドを指定する必要はありません。ドキュメントは設定されたフィールドのサブセットを含むことができます。しかし、ドキュメントのすべてのフィールドは、ドメインで設定されているフィールドに対応する必要があります。

ドキュメントを検索ドメインに追加するには

  1. 追加するドキュメントの ID と、検索できるフィールドまたは結果で戻り値として使用できる各フィールドを含む追加オペレーションを指定します。ドキュメントがすでに存在する場合、追加オペレーションによってドキュメントは置き換えられます(選択したフィールドだけを更新することはできません。ドキュメントは新しいバージョンで上書きされます)。たとえば、次のオペレーションはドキュメント tt0484562 を追加します。

    Copy
    { "type": "add", "id": "tt0484562", "fields": { "title": "The Seeker: The Dark Is Rising", "directors": ["Cunningham, David L."], "genres": ["Adventure","Drama","Fantasy","Thriller"], "actors": ["McShane, Ian","Eccleston, Christopher","Conroy, Frances", "Crewson, Wendy","Ludwig, Alexander","Cosmo, James", "Warner, Amelia","Hickey, John Benjamin","Piddock, Jim", "Lockhart, Emma"] } }
  2. ドキュメントバッチに追加オペレーションを含めて、ドメインにバッチをアップロードします。ドキュメントを個別にアップロードすることは避けて、オペレーションを最大 5 MB のバッチにまとめてください。(単一ドキュメントバッチを大量にアップロードすると、更新処理の速度が低下します)。データは Amazon CloudSearch コンソール経由でアップロードできます。これには cs-import-documents コマンドを使用するか、ドメインのドキュメントサービスエンドポイントにリクエストを直接投稿します。詳細については、「upload documents」を参照してください。

Amazon CloudSearch でのドキュメントの削除

削除オペレーションでは、ドメインのインデックスから削除するドキュメントを指定します。ドキュメントを削除すると検索できなくなり、結果に返されることもありません。

ドキュメントを削除するために更新を投稿するときは、削除する各ドキュメントを指定する必要があります。

インデックス サイズに対応するためにドメインが拡張されていた場合、大量のドキュメントを削除すると、次にインデックス全体を再構築するときに、ドメインが縮小されます。インデックスは定期的に自動再構築されますが、できる限り早く縮小するには、ドキュメントを削除しているときに、明示的にインデックス作成を実行します。

注記

ドキュメントを削除するには、削除オペレーションを含むドキュメントバッチをアップロードします。削除操作を行うバッチも含めて、検索ドメインにアップロードしたドキュメントバッチの合計数に対して請求されます。Amazon CloudSearch の料金の詳細については、「aws.amazon.com/cloudsearch/pricing/」を参照してください。

検索ドメインからドキュメントを削除するには

  1. 削除するドキュメントの ID を含む削除オペレーションを指定します。たとえば、次のオペレーションはドキュメント tt0484575 を削除します。

    Copy
    { "type": "delete", "id": "tt0484575" }
  2. ドキュメントバッチに削除オペレーションを含めて、ドメインにバッチをアップロードします。ドキュメントを個別に削除することは避けて、オペレーションを最大 5 MB のバッチにまとめてください。(単一ドキュメントバッチを大量にアップロードすると、更新処理の速度が低下します)。バッチは Amazon CloudSearch コンソール経由でアップロードできます。これには cs-import-documents コマンドを使用するか、ドメインのドキュメントサービスエンドポイントにリクエストを直接投稿します。詳細については、「upload documents」を参照してください。

Amazon CloudSearch 用にソースデータを処理

データをアップロードしてインデックスを作成するには、データを JSON 形式または XML 形式にする必要があります。コマンドラインツールおよび Amazon CloudSearch コンソールは、いくつかの一般的なファイルタイプ(PDF、Microsoft Excel、Microsoft PowerPoint、Microsoft Word、CSV、テキスト、HTML)から適切な JSON または XML 形式のファイルを自動的に生成することができます。Amazon CloudSearch 2011-02-01 API 用に整形されたバッチを処理して、それを 2013-01-01 形式に変換することもできます。

ほとんどのファイルタイプで、各ソースファイルは、生成された JSON または XML 形式の別々のドキュメントとして表されます。ファイルにメタデータが使用可能な場合は、メタデータが対応するドキュメントフィールドにマッピングされます。ドキュメントのメタデータから生成されるフィールドはファイルの種類によって異なります。ソースファイルのコンテンツは解析されて、単一のテキストフィールドになります。ファイルが 1 MB 以上のデータを含む場合、テキストフィールドにマッピングされるデータは切り捨てられるため、ドキュメントが 1 MB を超えることはありません。

CSV ファイルは扱いが異なります。CSV ファイルを処理するとき、Amazon CloudSearch は最初の 2 行のコンテンツを使用してドキュメントフィールドを定義し、残りの行は行ごとに別のドキュメントを作成します。docid という列ヘッダーがある場合、その列の値はドキュメント ID として使用されます。必要に応じて、docid 値は、許可されている文字セットに従うように正規化されます。ドキュメント ID では、任意の英字または数字と次の文字を使用できます。​_ - = # ; : / ? docid 列がない場合は、ファイル名と行番号に基づいて各ドキュメントの一意の ID が生成されます。

複数の種類のファイルをアップロードする場合、CSV ファイルは行ごとに解析され、非 CSV ファイルは個別のドキュメントとして扱われます。

注記

現在は、CSV ファイルのみが解析されて、自動的にカスタムフィールドデータが抽出され、複数のドキュメントが生成されます。

DynamoDB に保存されたデータを処理することもできます。Amazon CloudSearch は、テーブルから読み込んだ各項目を別のドキュメントとして表します。

Amazon CloudSearch コンソールを使用したソースデータの処理

Amazon CloudSearch コンソールを介してソースドキュメントまたは DynamoDB 項目をアップロードすると、Amazon CloudSearch JSON 形式に自動的に変換されます。コンソールを使用して、一度に最大 5 MB のデータをアップロードできます。必要に応じて、生成された JSON ファイルをダウンロードすることもできます。コンソールを介してデータをアップロードする方法の詳細については、「upload documents」と「Uploading DynamoDB Data」を参照してください。

Amazon CloudSearch コマンドラインツールを使用したソースデータの処理

cs-import-documents コマンドを使用して、ローカルファイル、Amazon S3 に保存されたデータ、DynamoDB テーブルのデータを処理し、インデックス作成のために検索ドメインにアップロードします。生成された JSON または XML ファイルをローカルに、または Amazon S3 に保存することもできます。

ソースデータを処理するには

  • cs-import-documents コマンドを実行し、--source オプションで処理するソースデータを指定します。複数のソースを指定して、複数の場所にあるデータを処理できます。例: --source c:\DataSet1 c:\DataSet2cs-import-documents コマンドでは、ファイル名、ディレクトリおよび S3 プレフィックスに次のワイルドカードを使用できます。?(任意の 1 文字に一致)、*(ゼロ個以上の文字に一致)、**(ゼロ個以上のディレクトリまたはプレフィックスに一致)。

    処理済みデータを検索ドメインに直接アップロードするには、--domain オプションを指定します。アップロードする代わりに、ローカルファイルシステムまたは Amazon S3 に処理済みデータを保存するには、--output オプションを指定します。デフォルトで、cs-import-documents はデータを JSON 形式で出力します。XML を生成するには、-format xml オプションを指定します。

    ローカルファイルシステムまたは Amazon S3 からデータを読み取る場合は、--modified-after オプションを使用して、特定の日時以降に変更されたファイルまたは Amazon S3 オブジェクトのみを処理することができます。DynamoDB テーブルからデータを読み取る場合は、テーブルの特定の読み取りポイントを示す開始キーと、読み取る行数を指定できます。start-hash-keystart-range-key--num-rows オプションの詳細については、「cs-import-documents 」を参照してください。

    たとえば、次のコマンドは myAmazingDataSet ディレクトリの内容を処理し、作成した XML ドキュメントバッチを c:\myAmazingDataSet\XML に保存します。

    Copy
    cs-import-documents --source c:\myAmazingDataSet\* --modified-after 2014-02-28T00:00:00PDT -format xml --output c:\myAmazingDataSet\XML

CSV データを処理するには

  • cs-import-documents コマンドを実行し、処理する CSV ファイルを --source オプションで指定します。デフォルトでは、次にようになります。

    • 各行は、別のドキュメントとして解析されます。--single-doc-per-csv オプションを指定して、この動作を無効にできます。

    • CSV ファイルのフィールド区切り文字はカンマ(,)であると想定されています。区切り文字は、--delimiter オプションを使って、セミコロン(;)やタブ(\t)などの別の文字に設定できます。

    • 各フィールドは単一値を含むと想定されています。フィールドから複数の値を取得するには、--multivalued オプションを使用して、複数値を含むフィールドを指定します(フィールドを指定しないと、docid 以外のすべてのフィールドが複数値フィールドとして処理されます)。

    • CSV ファイルで複数値フィールドの個々の値を分離するために使用される文字は、二重引用符(")であると想定されています。これは、--encapsulator オプションを使って、一重引用符(')などの別の文字に設定できます。

    • CSV ファイルでコメントを識別するために使用される文字は、ハッシュ文字(#)であると想定されています。コメント文字は、--comment-character オプションを使って、アスタリスク(*)などの別の文字に設定できます。

    たとえば、次のコマンドは myAmazingDataSet ディレクトリにあるタブ区切りの CSV ファイルを処理します。フィールドは、個別の値が単一引用符で囲まれた複数値フィールドとして扱われます。

    Copy
    cs-import-documents -d mydomain --source c:\myAmazingDataSet\*.csv --delimiter \t --multivalued --encapsulator '