バッチフィードでの v1 バージョニング

バッチフィードでは、エンティティのバージョンは、フィードのエンベロープの dateModified フィールドで判断されます。

{
  "@context": "http://schema.googleapis.com",
  "dateModified": "2018-12-28T06:30:00:123-07:00",
  "@type": "DataFeed",
  "dataFeedElement": [
    /* All the items that are part of this feed go here */
  ]
}

フィールド dataFeedElement にリストされるすべてのエンティティは、エンベロープにリストされるものと同じタイムスタンプを持ちます。

たとえば、次のフィードに 2 つのエンティティがあるとします。

{
  "@context": "http://schema.googleapis.com",
  "@type": "DataFeed",
  "dateModified": "2018-12-28T06:30:00:123-07:00",
  "dataFeedElement": [
    {
      "@type": "Restaurant",
      "@id": "http://www.provider.com/somerestaurant",
      ...
    },
    {
      "@type": "Menu",
      "@id": "http://www.provider.com/somerestaurant/menu/1"
      ...
    }
  ]
}

メニュー エンティティとレストラン エンティティは、受信されて処理されると、「2018-12-28T06:30:00:123-07:00」として個別にバージョニングされます。

増分アップデートによるバージョニング

インベントリの更新を使用してエンティティを送信する場合、バージョンは update_time フィールド（追加/更新呼び出しの場合）または delete_time フィールド（削除呼び出しの場合）で設定されます。これらのフィールドは省略可能です。デフォルトのタイムスタンプは、Google が呼び出しを受信した時点に設定されます。

例 1: update_time を明示的に設定

2018-12-28T06:30:10:123-07:00 にまったく新しいレストランについて次の増分呼び出しを受信したとします。データフィードで v1 在庫スキーマが使用されている場合の、ID が「http://www.provider.com/somerestaurant」のエンティティの HTTP POST リクエストは次のようになります。

POST v2/apps/provider-project/entities/http%3A%2F%2Fwww.provider.com%2Fnewrestaurant:push
Host: actions.googleapis.com
Content-Type: application/ld+json

以下の JSON ペイロードの本文には、update_time フィールドが含まれています。ID が「http://www.provider.com/somerestaurant」のエンティティの場合、このエンティティのバージョンは受信時ではなく 6:30:00 になります（10 秒後の 6:30:10）。

{
// This envelope is to be used for incremental.
  "entity": {
    // Note: "data" is not serialized as a string in our example for readability.
    "data": "[entity in JSON format serialized as a string]",
    "vertical": "FOODORDERING"
  },
  "update_time":"2018-12-28T06:30:00:123-07:00"
}

例 2: update_time が暗黙的に設定される

2018-12-28T06:30:10:123-07:00 にまったく新しいレストランについて次の増分呼び出しを受信したとします。フィードで v1 在庫スキーマが使用されていると仮定して、ID が「http://www.provider.com/somerestaurant」エンティティに対する HTTP POST リクエストは次のようになります。

POST v2/apps/provider-project/entities/http%3A%2F%2Fwww.provider.com%2Fnewrestaurant:push
Host: actions.googleapis.com
Content-Type: application/ld+json

以下の JSON ペイロードの本文には update_time フィールドが含まれません。そのため、ID が「http://www.provider.com/somerestaurant」のエンティティでは、このエンティティのバージョンが 6:30:10 になります。

{
// This envelope is to be used for incremental.
  "entity": {
    //Note: "data" is not serialized as a string in our example for readability.
    "data": "[entity in JSON format serialized as a string]",
    "vertical": "FOODORDERING"
  }
}

バッチと増分の間のバージョニング

Google に送られたエンティティは、そのエンティティが最新バージョンである場合にのみ処理され、提供されます。バッチで送信されたエンティティは通常、処理に数日かかりますが、増分 API で送信されたエンティティはすぐに処理されます。

ベスト プラクティス

  • システムでエンティティが変更されたタイミングに応じて、update_time フィールドと dateModified フィールドをそれぞれ増分とバッチで設定します。
  • バッチフィード（ファイル）に複数のトップレベル エンティティがリストされている場合（たとえば、レストランをサービスやメニューと組み合わせる場合など）、エンティティのデータが更新されるたびにタイムスタンプを更新します。
  • 増分呼び出しでは、update_time フィールドを明示的に設定することを強くおすすめします。
  • 増分呼び出しが行われた後は、Google が再び取得する前に、対応するフィードのタイムスタンプ（dateModified）も更新する必要があります。

例

Google は、まったく新しいレストランについて、2018 年 12 月 28 日の午前 11 時に次のファイルを取得します。

{
  "@context": "http://schema.googleapis.com",
  "@type": "DataFeed",
  "dateModified": "2018-12-28T06:30:00-07:00",
  "dataFeedElement": [
    {
      "@type": "Restaurant",
      "@id": "http://www.provider.com/newrestaurant",
      ...
    },
    {
      "@type": "Menu",
      "@id": "http://www.provider.com/newrestaurant/menu/1"
      ...
    }
    {
      "@type": "Service",
      "@id": "http://www.provider.com/newrestaurant/service/1"
      ...
    }
  ]
}

これらのエンティティは正常に処理され、「2018-12-28T06:30:00-07:00」としてバージョニングされます。バッチフィードは処理に時間がかかるため、通常は 2 日後に配信されます。

しかし、午後 1 時にパートナーのシステムでレストランの電話番号が更新され、次の増分コールが発生します。Google は 13:05（5 秒後に）にこの着信を受け取ります。

POST v2/apps/provider-project/entities/http%3A%2F%2Fwww.provider.com%2Fnewrestaurant:push
Host: actions.googleapis.com
Content-Type: application/ld+json
{
// This envelope is to be used for incremental.
  "entity": {
    //Note: "data" is not serialized as a string in our example for readability.
    "data": "[entity in JSON format serialized as a string]",
    "vertical": "FOODORDERING"
  },
  "update_time":"2018-12-28T13:00:00-07:00"
}

update_time は明示的に指定されており、以前のバージョン（同じ日の午前 6:30）よりも新しい（新しい）ため、レストラン エンティティのバージョンは「2018-12-28T13:00:00-07:00」になります。ただし、メニューとサービス エンティティは引き続き「2018-12-28T06:30:00-07:00」としてバージョニングされます。

増分呼び出しがあったため、バッチフィードは対応する新しいタイムスタンプで更新されます。また、対応する変更が関連するエンティティに適用されます（レストラン エンティティの電話番号が更新されます）。

{
  "@context": "http://schema.googleapis.com",
  "@type": "DataFeed",
  "dateModified": "2018-12-28T13:00:00-07:00",
  "dataFeedElement": [
    {
      "@type": "Restaurant",
      "@id": "http://www.provider.com/newrestaurant",
      ...
    },
    {
      "@type": "Menu",
      "@id": "http://www.provider.com/newrestaurant/menu/1"
      ...
    }
    {
      "@type": "Service",
      "@id": "http://www.provider.com/newrestaurant/service/1"
      ...
    }
  ]
}

翌日（2018 年 12 月 29 日）の午後 11 時に、フィードが再び取得されます。レストランにはまだ同じバージョン（12 月 28 日の午後 1 時）があるため、このエンティティは破棄され、現在のバージョンが保持されます。ただし、Menu エンティティと Service エンティティは新しいバージョンで更新されます。

サイトマップのタイムスタンプ

サイトマップの last-modified レスポンス ヘッダーは、エンティティのバージョンには影響しません。これは、Google がフィードを取得するタイミングに影響します。

ベスト プラクティス

  • すべてのファイルが最新で、取得する準備ができている場合にのみ、レスポンス ヘッダーを更新します。
  • update_time と delete_time を増分で明示的に使用します。
  • update_time、delete_time、dateModified を、ユーザー側でデータが変更されたタイミングに設定します。