ローカル サービス広告（LSA）は、アグリゲーターと提携して、Google.com にアグリゲーターのリスティング（またはプロバイダ）を表示します。このガイドでは、アグリゲーターがプロバイダに関する LSA 構造化データを指定する方法について説明します。具体的には、LSA と統合するためにアグリゲータが実装する必要がある API エンドポイントのセットについて説明します。
用語集
アグリゲータ（またはパートナー）: サービスを提供するプロバイダを統合するパートナー。そのデータが LSA に提供される場合があります。
サードパーティ プロバイダ（またはリスティング）: 個々の小規模ビジネス（例:Joe’s plumbing）が、アグリゲータとビジネス上の関係を持っている可能性があります。アグリゲーターは、これらのビジネスに関する情報をローカル サービスに提供します。
概要
アグリゲーターは、フィードを使用して、プロバイダ（事業者）に関するデータをローカル サービスに提供します。各フィードは、複数のプロバイダに関するデータで構成されます。フィード内では、単一のプロバイダに関するデータはフィード アイテムによってカプセル化されます。各フィードには、フィードの鮮度を示すフィード タイムスタンプも指定されています。各フィードでは、フィードタイプも指定します。これは、以下で説明するように、プロバイダ プロフィールまたはプロバイダのレビューに関するデータです。
フィードタイプ
最初の統合では、各フィードは次のいずれかのフィードタイプになります。
プロフィール フィード: プロバイダのプロフィールに関する情報を提供します。各フィード アイテムには、特定のプロバイダに関するプロフィール情報がカプセル化されています。これには、一意のビジネス ID、ビジネス名、サービス提供地域、提供サービス、営業時間などが含まれます。フィード アイテムには、このビジネスの配信メタデータ（月額予算額、広告ステータスなど）も含まれます。
レビュー フィード: プロバイダのレビューに関する情報を提供します。各フィード アイテムには、特定のプロバイダに関する詳細なユーザー レビューのリストがカプセル化されています。各ユーザー レビューは、ユーザー名、評価（1 ～ 5）、レビュー テキスト、レビューのタイムスタンプなどで構成されます。
特定のフィールドとそのセマンティクスについて詳しくは、プロフィール フィードとレビュー フィードをご覧ください。
フィードの取り込み
フィードデータは JSON としてシリアル化されます。データを送信するために、LSA はプルメカニズムのみをサポートします。プッシュ メカニズムをサポートする計画もあります。
プル メカニズム
プルメカニズムでは、アグリゲータは JSON オブジェクトを送受信する一連の事前定義された REST エンドポイント（URL）をサポートします。これは、ウェブサーバーで 1 つ以上のファイルをホストするのと同様です。LSA は、これらの URL に HTTP GET リクエストを定期的に発行してデータを取得します。事前定義された URL の詳細については、次の API エンドポイントのセクションをご覧ください。
プッシュ メカニズム
プッシュ メカニズムでは、LSA はアグリゲータが呼び出してデータを提供するためのエンドポイントを提供します。意味的には pull と同じですが、アグリゲータが特定のデータをローカル サービスに push したい場合に柔軟性を提供します。プロトコルで説明されているすべてのセマンティクス、ルール、制約は、プッシュとプルに同じように適用されます。
API エンドポイント
アグリゲータは、プロフィール フィード用とレビュー フィード用の 2 つのエンドポイントをサポートする必要があります。
推奨エンドポイントのパス
エンドポイントに次のようなバージョン情報を含めることをおすすめします。まず、v1 から始めます。
| エンドポイント | パス |
|---|---|
| プロフィール フィード | /feeds/{version}/profile |
| レビュー フィード | /feeds/{version}/review |
エンドポイント パラメータ
| パラメータ | 説明 |
|---|---|
maxresults |
これは、1 ページでリクエストできるフィード アイテム数の上限です。 |
nextpagetoken |
結果の次のページを取得するためのページ設定トークン |
エンドポイント認証
認証では HTTP 基本アクセス認証が使用されます。認証用のユーザー名とパスワードは base64 でエンコードされます。下図を参考にしてください。
username「Authorization」（例示）passwordJ9adfdsafc3RfMjpVU1yif5XMw」（説明用）
Push 用 SFTP ドロップボックス
Dropbox のパス: partnerupload.google.com:19321
警告: この SFTP ドロップボックスにアップロードされたファイルは、24 時間後に自動的に削除されます。
エンドポイント認証
公開鍵/秘密鍵のペア（推奨）
- こちらのチュートリアルを使用して、鍵ペアを生成します。
- LSA に公開鍵を送信し、認証用の秘密鍵を保持する
- LSA は公開鍵を使用してユーザー名を生成し、アグリゲータに返送します。
パスワード認証
- LSA はユーザー名とパスワードを生成してアグリゲータに返送します
SFTP コマンドのクイック リファレンス
ログインします。このコマンドを使用してログインします。（秘密鍵を使用しない場合は -i
を省略します）。 sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comファイルをコピーします。ファイルをリモート システムにコピーします。
lls/lcdを使用してローカル システムにls/cdし、ファイルを見つけることができます。次に、次のコマンドでファイルをコピーします。put <path_to_local_file>確認。
lsを使用して、SFTP ディレクトリ内のフォルダとファイルの一覧を表示し、ファイルがリモート システムにコピーされたことを確認します。
フィードのカテゴリ
前述のように、各フィードはファイルに類似しており、複数のフィード アイテムで構成されています。各フィード アイテムには、特定のプロバイダ（一意のビジネス ID）に関するデータがカプセル化されています。各フィードには、フィードの鮮度を示すタイムスタンプもあります。フィード カテゴリは、LSA が特定のフィードを解釈する方法を指定します。フィードには、次の 2 つのカテゴリがあります。
スナップショット フィードには、特定のタイムスタンプにおけるプロバイダ（アグリゲータの下）の完全なリストが含まれます。このスナップショット フィードを処理すると、次のセマンティクスが適用されます。
フィードに存在するプロバイダについては、システムは LSA データベースでこのプロバイダのデータを更新します（たとえば、初めて検出された場合は新しいプロバイダを作成し、以前のフィードで処理されたプロバイダの場合はプロバイダのデータを更新します）。
現在 LSA データベースに存在し、フィードに存在しないアグリゲータのプロバイダは削除されます。
更新（または増分）フィードには、特定のタイムスタンプにおける（アグリゲータの）プロバイダのリストの一部が含まれます。増分フィードの処理後、次のセマンティクスが適用されます。
フィードに存在するプロバイダについては、以前のスナップショット フィードで作成されたプロバイダであれば、LSA データベースでそのプロバイダのデータが更新されます。（たとえば、プロバイダが初めて検出された場合は、no-op になります）。
LSA データベースに存在し、フィードに存在しないプロバイダについては、何も行われません（つまり、このプロバイダに変更はありません）。
プロフィール フィードとレビュー フィードのセマンティクスは若干異なります。処理の詳細については、個々のフィードのセマンティクスをご覧ください。
プロフィール フィード: * プルベースのスナップショット フィード * プッシュベースのスナップショット フィード * プッシュベースの更新フィード レビュー フィード: * プルベースのスナップショット フィード * プッシュベースのスナップショット フィード
次の場合は、個別のプロフィール フィードが必要です。
Google 保証または Google によって審査済みバッジの対象と見なされるプロバイダ。
バッジの対象外のプロバイダ。
例
スナップショット フィード
スナップショット フィードは、プロバイダの完全なリストで構成されます。たとえば、アグリゲータが 100 のプロバイダを LSA に取り込む場合、スナップショット フィードには 100 のプロバイダすべての最新の状態が含まれている必要があります。
仕組み
以下は、プロフィール フィードのスナップショット カテゴリの仕組みを示す簡単な例です。
- スナップショット 1 には Pro 1、Pro 2 が含まれます
- スナップショット 2 には Pro 1、Pro 3 が含まれています
スナップショット 1 の処理後、LSA データベースには Pro 1 と Pro 2 が含まれます。スナップショット 2 の処理中に、LSA は Pro 1 を更新し、Pro 3 を作成して、Pro 2 を削除します。つまり、スナップショット 2 の処理後、LSA データベースには Pro 1 と Pro 3 が含まれます。
フィードを更新する（増分）
更新フィードには、アグリゲータの下にあるプロバイダの部分的なリストが含まれています。たとえば、アグリゲータが以前に提供した 100 のプロバイダのうち 5 つだけを更新したい場合、更新フィードにはそれら 5 つのプロバイダの最新の状態のみを含める必要があります。
仕組み
以下は、「プロフィール フィード」の更新カテゴリの仕組みを示す簡単な例です。
- 更新 1: Pro 1、Pro 2
- 更新 2: Pro 1、Pro 3
更新 1 の処理後、LSA データベースには Pro 1 と Pro 2 が含まれます。Update 2 の処理中に、LSA は Pro 1 を更新し、Pro 3 を作成します。Pro 2 は変更されていません。つまり、Update 2 の処理後、LSA データベースには Pro1、Pro2、Pro 3 が含まれます。
スナップショットと pull の意味
スナップショット フィード + プル メカニズムには、次の制限があります。
- パートナーがプロバイダの追加や削除、プロフィール情報の更新、広告の一時停止、予算の変更を行う場合、数時間の遅延が発生することがあります。遅延は、pull リクエストの頻度に直接関係します。
- 緊急のデータ更新については、1 回限りのアドホック プルを手動でサポートする必要がある場合があります。
増分サポートとプッシュ サポートの影響
フィードの更新とプッシュ メカニズムを導入すると、次のような改善が期待できます。
- パートナーは、スナップショット フィードを push または pull で配信できます。エンドポイント（プル用）の維持を希望しないパートナーは、プッシュを使用してエンドポイントの維持費を削減できます。パートナーがすでにプルでスナップショット フィードをサポートしている場合は、プルでスナップショットの配信を継続できます。
- パートナーは増分を使用して、プロファイルの変更があるプロバイダのサブセットのみを更新できます。これにより、プロファイル データの更新頻度が向上します。
- スナップショットと増分、プッシュとプルを選択する方法については、このセクションで推奨される統合アプローチをご覧ください。
推奨される統合アプローチ
パートナーは、プッシュまたはプルを介して定期的なスナップショット フィードを用意する必要があります。これにより、LSA は、アップデートの失敗時にロールバックやシステム復元などの緊急事態に対処できます。
- プッシュ メカニズムでは、パートナーはベースライン データの鮮度を保証するために、2 時間ごとにスナップショット プロファイル フィードをプッシュし、6 時間ごとにレビュー フィードをレビューする必要があります。
- プルメカニズムを使用すると、LSA は 2 時間ごとにスナップショット プロファイル フィードをプルし、6 時間ごとにフィードを確認して、ベースライン データの鮮度を保証します。
- スナップショット フィードを配信するために必要なメカニズムは、プッシュとプルのいずれか一方のみです。両方は必要ありません。
必要に応じて、データの鮮度を高めたいパートナーは、プッシュで更新フィードを送信できます。LSA は更新フィードを取得しません。
- 更新フィードは、次のスナップショットを待たずに、最後のスナップショット以降に変更されたアイテムを伝播するために使用されます。
- LSA では、2 回のプッシュの間に 5 分以上の間隔を設けることを推奨しています。
- 更新フィードでフィード項目を適切にバンドルすることをおすすめします。5 つのプロバイダを更新する場合、LSA は、5 つの更新フィードをそれぞれ 1 つのフィード項目でプッシュするのではなく、1 つの更新フィードを 5 つのフィード項目でプッシュすることを推奨します。
- LSA は、レビュー フィードではなく、プロフィール フィードでのみ増分フィードをサポートしています。
LSA は、メタデータの feedTimestampMicros フィールドを尊重して、データの一貫性を保証します。同じプロを更新する新しいアイテムが取り込まれている場合、古いタイムスタンプのフィード アイテムはスキップされ、古いアイテムが導入されるのを防ぎます。スナップショット フィードと更新フィードの両方で feedTimestampMicros を使用してデータの鮮度を正しく反映するのは、パートナーの責任です。
パートナー様は、Reporting API を使用して、プロバイダごとの見込み顧客と請求に関する情報を取得する必要があります。