Esta página foi traduzida pela API Cloud Translation.

Controle de versão v1 em feeds em lote

Nos feeds em lote, a versão de uma entidade é determinada pelo campo dateModified no envelope do feed:

{
  "@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 */
  ]
}

Todas as entidades listadas no campo dataFeedElement terão o mesmo carimbo de data/hora, conforme listado no envelope.

Por exemplo, você pode ter o seguinte feed com duas entidades:

{
  "@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"
      ...
    }
  ]
}

Depois de recebidas e processadas, as entidades do cardápio e do restaurante terão uma versão individual de "2018-12-28T06:30:00:123-07:00".

Controle de versões com atualizações incrementais

Ao enviar uma entidade usando atualizações de inventário, a versão é definida no campo update_time (no caso de uma chamada de adição/atualização) ou no campo delete_time (no caso de uma chamada de exclusão). Como esses campos são opcionais, o carimbo de data/hora padrão é definido como quando o Google recebeu a chamada.

Exemplo 1: update_time definido explicitamente

Suponha que a seguinte chamada incremental seja recebida em 2018-12-28T06:30:10:123-07:00 para um restaurante completamente novo. Confira a solicitação HTTP POST para essa entidade com o ID "http://www.provider.com/somerestaurante", supondo que o feed de dados use o esquema de inventário v1:

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

Abaixo, o corpo do payload JSON contém o campo update_time. A entidade com o ID "http://www.provider.com/somerestaurante" faz com que ela tenha o controle da versão como 6:30:00, e não quando foi recebida (10 segundos depois, às 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"
}

Exemplo 2: update_time definido implicitamente

Suponha que a seguinte chamada incremental seja recebida em 2018-12-28T06:30:10:123-07:00 para um restaurante completamente novo. Confira a solicitação POST HTTP para essa entidade com o ID "http://www.provider.com/somerestaurante", supondo que o feed use o esquema de inventário v1:

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

Abaixo, o corpo do payload JSON não contém o campo update_time. Portanto, a entidade com ID "http://www.provider.com/somerestaurante" resulta na versão dessa entidade como 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"
  }
}

Controle de versão entre lote e incremental

Uma entidade enviada ao Google só será processada e veiculada se tiver a versão mais recente. Geralmente, as entidades enviadas por lote levam alguns dias para serem processadas. Já as entidades enviadas por meio da API incremental são processadas imediatamente.

Práticas recomendadas

Defina os campos update_time e dateModified de modo incremental e em lote, respectivamente, de acordo com quando a entidade foi modificada nos sistemas.
Se um feed em lote (arquivo) listar mais de uma entidade de nível superior (por exemplo, você pareia seus restaurantes com serviços e menus), atualize o carimbo de data/hora conforme os dados de uma entidade são atualizados.
Em chamadas incrementais, é altamente recomendável definir explicitamente o campo update_time.
É fundamental que, quando uma chamada incremental for feita, o carimbo de data/hora do feed correspondente (dateModified) também seja atualizado antes que o Google o busque novamente.

Exemplo

O Google busca o seguinte arquivo às 11h de 28/12/2018 para um restaurante completamente novo:

{
  "@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"
      ...
    }
  ]
}

O processamento dessas entidades é concluído e a versão delas é "2018-12-28T06:30:00-07:00". Como o processamento dos feeds em lote leva tempo, eles geralmente são veiculados dois dias depois.

No entanto, às 13h, o sistema do parceiro atualiza o número de telefone do restaurante, o que resulta na seguinte chamada incremental, que o Google recebe às 13h05 (5 segundos depois):

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"
}

O update_time é fornecido explicitamente e é maior (mais recente) que a versão anterior (6h30 do mesmo dia), então a entidade do restaurante agora tem o controle de versão "2018-12-28T13:00:00-07:00". No entanto, a versão das entidades de menu e serviço ainda é "2018-12-28T06:30:00-07:00".

Como houve uma chamada incremental, o feed em lote é atualizado com o novo carimbo de data/hora correspondente. Além disso, as mudanças correspondentes são aplicadas às entidades relevantes (a entidade do restaurante tem o número de telefone atualizado).

{
  "@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"
      ...
    }
  ]
}

No dia seguinte (29/12/2018), às 23h, o feed é buscado novamente. O restaurante ainda tem a mesma versão (13h de 28 de dezembro), então essa entidade é descartada e a versão atual é mantida. No entanto, as entidades de Menu e Serviço são atualizadas para uma nova versão.

Carimbos de data/hora do sitemap

O cabeçalho de resposta last-modified no sitemap não afeta a versão de uma entidade. Ela afeta quando o feed é buscado pelo Google.

Práticas recomendadas

Atualize o cabeçalho de resposta somente quando todos os arquivos estiverem atualizados e prontos para a busca.
Use explicitamente update_time e delete_time de forma incremental.
Defina update_time, delete_time e dateModified para quando os dados mudarem no seu lado.