Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Varejo. Para usar a pesquisa de varejo na fase GA restrita, entre em contato com a equipe de vendas do Cloud.

Se você estiver usando apenas o Recommendations AI, permaneça no Console do Recommendations e consulte a documentação do Recommendations AI.

Como atualizar o inventário da pesquisa de varejo

Embora os métodos de criação, leitura, atualização e exclusão (CRUD, na sigla em inglês) Product sejam usados para modificar amplamente os atributos de um Product, há um conjunto de métodos Product que pode ser usado para atualizar campos específicos de inventário com níveis diferentes de granularidade. Os campos Product a seguir são considerados campos de inventário:

  • Product.price_info
  • Product.availability
  • Product.available_quantity
  • Product.fulfillment_info

Métodos de atualização de inventário

Alterações nas informações de inventário de um produto podem ocorrer com muito mais frequência do que as alterações nas informações de catálogo. Assim, um conjunto especializado de métodos é fornecido para lidar com grandes volumes de atualizações específicas do inventário. Esses métodos são assíncronos devido a otimizações downstream compatíveis com centenas de atualizações simultâneas por produto, sem sacrificar o desempenho.

Atualizações incrementais

fulfillment_info é usado com frequência para codificar a disponibilidade de fulfillment em nível de lugar para um Product. Em alguns casos, a disponibilidade do fulfillment para alguns locais específicos pode mudar, e você pode decidir emitir atualizações que descrevem essa mudança em vez de usar o método UpdateProduct para especificar novamente as informações de fulfillment de todo o produto.

Nesses casos, os métodos AddFulfillmentPlaces e RemoveFulfillmentPlaces podem ser usados para atualizar incrementalmente as alterações de fulfillment de um produto com base nos IDs do lugar. são adicionados ou removidos para um determinado tipo de fulfillment.

Java

Para saber como instalar e usar a biblioteca de cliente do Retail, consulte Bibliotecas de cliente do Retail. Para mais informações, consulte a documentação de referência da API Retail em Java.

public static AddFulfillmentPlacesResponse addFulfillmentPlaces(
    Product productToUpdate, String fulfillmentInfoType, ImmutableList<String> placeIds)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  AddFulfillmentPlacesRequest request = AddFulfillmentPlacesRequest.newBuilder()
      .setProduct(productToUpdate.getName())
      .setType(fulfillmentInfoType)
      .addAllPlaceIds(placeIds)
      .setAddTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .build();

  AddFulfillmentPlacesResponse response = productClient
      .addFulfillmentPlacesAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    type: "pickup-in-store"
    place_ids: "store0"
    place_ids: "store1"
    add_time: {
      seconds: 100
      nanos: 100
    }
    allow_missing: true
  }
  

Esta amostra de AddFulfillmentPlacesRequest adiciona o tipo de fulfillment "pickup-in- store" para inserir os códigos "store0" e "store1" do produto especificado. Como AddFulfillmentPlacesRequest.allow_missing está definido como verdadeiro, mesmo que o produto ainda não exista, as informações do inventário atualizado serão armazenadas para quando o produto for criado. A atualização é carimbada com AddFulfillmentPlacesRequest.add_time para evitar que atualizações desatualizadas modifiquem o status de fulfillment desses IDs de local. Esses recursos são discutidos com mais detalhes nas seções a seguir.

O comportamento é idêntico para RemoveFulfillmentPlacesRequest, e o esquema é muito semelhante.

Atualizações não incrementais

price_info, availability e available_quantity não podem ser atualizados de forma incremental porque representam inventário no nível de produto, em vez de informações no nível do local. Além disso, é recomendável emitir atualizações não incrementais para fulfillment_info em vez de apenas alterações incrementais. Nesses casos, o método SetInventory é recomendado.

Java

Para saber como instalar e usar a biblioteca de cliente do Retail, consulte Bibliotecas de cliente do Retail. Para mais informações, consulte a documentação de referência da API Retail em Java.

public static SetInventoryResponse setInventoryWithMask(Product productToUpdate,
    FieldMask updateMask)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetMask(updateMask)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: {
      name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
      availability: IN_STOCK
      fulfillment_info: {
        type: "pickup-in-store"
        place_ids: "store0"
        place_ids: "store1"
        place_ids: "store2"
        place_ids: "store3"
      }
      fulfillment_info: {
        type: "same-day-delivery"
      }
    }
    set_time: {
      seconds: 100
      nanos: 100
    }
    set_mask: {
      paths: "availability"
      paths: "fulfillment_info"
    }
    allow_missing: true
  }
  

Nesta solicitação específica, os campos SetInventoryRequest.product.fulfillment_info são descrições completas dos IDs de lugar qualificados de cada tipo de fulfillment, em vez das especificações incrementais. A atualização para "same-day-delivery" indica que nenhum ID de lugar está qualificado para esse tipo de fulfillment para esse produto. Todos os outros tipos de fulfillment não são atualizados nesta solicitação.

Por padrão,SetInventory atualizará todos os campos de inventário se SetInventory.set_mask não estiver definido ou estiver vazio. Se a máscara não estiver vazia ou se um campo de inventário não estiver explicitamente listado em SetInventoryRequest.set_mask, qualquer valor especificado para esse campo será ignorado na solicitação de atualização.

Assim como acontece com as atualizações incrementais, o campo SetInventoryRequest.set_time pode ser usado para definir um horário de atualização que será a última hora de atualização registrada de todos os campos de inventário atualizados.

Proteções de carimbo de data/hora para atualizações de inventário

Há vários caminhos diferentes para atualizar os campos de inventário de um produto. Para proteger contra atualizações fora de ordem, cada campo de inventário é associado a um horário de atualização mais recente.

O horário da última atualização é registrado para price_info, availability, available_quantity e cada par de (fulfillment_info.place_ids, fulfillment_info.type).

Os métodos AddFulfillmentPlaces, RemoveFulfillmentPlaces e SetInventory permitem que o autor da chamada especifique uma o horário de atualização do momento em que a solicitação é emitida. Esse tempo de atualização é comparado com o horário da atualização mais recente registrado para os campos de inventário relevantes, e a atualização será confirmada se e somente se o tempo de atualização for estritamente posterior ao da atualização mais recente

Por exemplo, suponha que o ID do lugar "store1" tenha o tipo de fulfillment "pickup-in- store" ativado e o horário da última atualização registrado tenha sido definido como T. Se RemoveFulfillmentPlacesRequest.type = "pickup-in-store" eRemoveFulfillmentPlacesRequest.place_ids contém"store1", a solicitação será limpa"pickup-in-store" de"store1" somente se a RemoveFulfillmentPlacesRequest.remove_time é posterior ao horárioT de dados. O mesmo acontece para AddFulfillmentPlacesRequests.

SetInventory opera de maneira semelhante para atualizar price_info, availability e available_quantity. Ao atualizar fulfillment_info, um SetInventoryRequest está solicitando implicitamente a adição de todos os IDs de lugar especificados para um determinado tipo de fulfillment e a remoção de todos os não existentes.

Portanto, quando SetInventoryRequest for processado, a atualização fulfillment_info será convertida implicitamente em um AddFulfillmentPlacesRequest e RemoveFulfillmentPlacesRequest para cada tipo de fulfillment especificado. Isso significa que, se algum lugar "store1" atual com fulfillment "pickup-in-store" tiver um horário da última atualização T mais recente do que SetInventoryRequest.set_time, a adição/adicionar implícita remova em "store1" e "pickup-in-store" não será aplicado.

Como pré-carregar informações de inventário

Cada um dos métodos de atualização de inventário permite que o autor da chamada defina allow_missing na solicitação. Quando allow_missing for definido como verdadeiro, uma atualização de inventário para um Product inexistente será processada como se o Product existisse de acordo com as especificações do método. As informações de inventário serão retidas por no máximo dois dias se o Product correspondente não for criado por CreateProduct dentro desse período.

Java

public static SetInventoryResponse setInventory(Product productToUpdate)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Quando usar os métodos Product

Embora seja possível atualizar campos de inventário com os métodos CRUD do produto, o autor da chamada precisa estar explicitamente ciente dos efeitos nas informações de inventário existentes ou preexistentes.

Esses são métodos síncronos, ou seja, as otimizações downstream usadas para métodos de inventário não se aplicam e pode ficar caro depender desses métodos para atualizações frequentes de inventário. Sempre que possível, prefira usar os métodos de atualização de inventário mencionados acima.

CreateProduct

Quando CreateProduct é invocado com qualquer campo de inventário definido, os valores fornecidos em CreateProductRequest.product modificam quaisquer valores pré-carregados para os respectivos campos. Se nenhum campo de inventário for definido, todas as informações de inventário preexistentes serão usadas automaticamente.

Além disso, o horário da atualização mais recente dos campos de inventário modificados será redefinido para a hora da chamada de método.

CreateProduct com inventário pré-carregado

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
  }
}

Nesse exemplo, o produto criado não tem nenhum campo de inventário definido, o que significa que as informações de inventário pré-carregadas serão usadas automaticamente se atualizadas usando os métodos de atualização de inventário. Isso pode ser útil quando as atualizações de inventário são separadas das atualizações de catálogo e você quer que um Product recém-criado seja sincronizado com as informações de inventário existentes.

CreateProduct com inventário explícito

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
    availability: OUT_OF_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
}

Neste exemplo, uma Product é criada com campos de inventário definidos explicitamente. Esses campos substituirão os valores preexistentes, ignorando o horário da atualização mais recente dos campos correspondentes. Assim, a Product recém-criada terá a disponibilidade definida como OUT_OF_STOCK, e nenhum ID de lugar será compatível com os tipos de fulfillment "pickup-in-store" e "same-day-delivery".

CreateProduct com informações de inventário pode ser útil se você não tiver certeza se todas as informações de inventário pré-carregadas estão corretas e prefere definir explicitamente o inventário no momento da criação de Product para sincronizar totalmente o catálogo e o inventário.

UpdateProduct

Quando UpdateProduct é invocado e a máscara de campo UpdateProductRequest.update_mask contém qualquer campo de inventário, os valores fornecidos no UpdateProductRequest.product substituem quaisquer valores pré-carregados para os respectivos campos.

Além disso, o horário da atualização mais recente dos campos de inventário modificados será redefinido para a hora da chamada de método.

PROTO

{
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    availability: IN_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
      place_ids: "store0"
      place_ids: "store1"
      place_ids: "store2"
      place_ids: "store3"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
  update_mask: {
    paths: "availability"
    paths: "fulfillment_info"
  }
}

Este exemplo é muito semelhante ao exemplo SetInventory, mas a atualização é garantida para ser aplicada independentemente do horário da atualização mais recente de cada campo de inventário.

UpdateProduct para inventário pode ser útil quando uma sincronização completa em informações de inventário é necessária ao ignorar as proteções de carimbo de data/hora.

Embora seja possível pré-carregar informações de inventário usando UpdateProduct definindo UpdateProductRequest.allow_missing como true para realizar um comando Product, o método exige a configuração de campos de catálogo específicos, como UpdateProductRequest.product.title. Assim, é recomendável usar os métodos de atualização de inventário para pré-carregar casos de uso.

DeleteProduct

Quando DeleteProduct for invocado, todas as informações de inventário existentes do produto especificado em DeleteProductRequest.name será excluído, incluindo todos os registros do horário da atualização mais recente de cada campo de inventário.