Visão geral da API de fontes de dados do comerciante

Esta página mostra como criar e atualizar de forma programática as fontes de dados que permitem inserir produtos. As fontes de dados automatizadas facilitam o envio de dados do produto ao Google. As fontes de dados automatizadas garantem que as informações mais atualizadas sobre produtos relevantes do seu site cheguem ao Google.

A API Content for Shopping só permite criar fontes de dados principais. Com a API Merchant Data Sources, é possível criar os seguintes tipos de fontes de dados:

• Fontes de dados de produtos principais
• Fontes de dados complementares de produtos
• Origens de dados de inventário local
• Origens de dados de inventário regional
• Fontes de dados de promoções
• Fontes de dados de avaliações do produto
• Fontes de dados de avaliações do comerciante

A API Content for Shopping só permite gerenciar fontes de dados com entrada de arquivo. A API Merchant permite gerenciar origens de dados com entradas de arquivo e API.

Com a API Merchant Data Sources, é possível fazer o seguinte:

• Crie uma nova fonte de dados principal com um feedLabel e um contentLanguage específicos.
• Crie uma fonte de dados que não tenha os campos feedLabel e contentLanguage definidos. Com esse tipo de fonte de dados, você pode segmentar vários países para seus produtos, inserindo itens com diferentes combinações de feedLabel e contentLanguage em uma única fonte de dados.
• Crie uma fonte de dados complementar para vincular a uma fonte de dados principal.
• Configure uma programação para uma fonte de dados de arquivos.
• Inscreva sua conta para o gerenciamento automático de fontes de dados.
• Gerenciar fontes de dados da API.
• Gerencie a regra padrão das fontes de dados usando as fontes de dados de produtos principais.
• Use outros tipos de fontes de dados, como promoções.

Não é possível usar a API Merchant para inserir produtos em uma fonte de dados que contenha produtos locais e on-line. Para mais informações sobre os canais de fontes de dados, consulte Canais.

Pré-requisitos

• Sua conta precisa ter sido migrada para feeds de uma única localidade.

• Para verificar se a conta já foi migrada para a divisão de destino de dados, use a lista de fontes de dados ou os métodos de acesso. Caso contrário, você vai receber a mensagem de exceção abaixo e precisará entrar em contato com o suporte.

  This account is in the data sources migration process and can't be used with
  this API yet. Contact support for more info on when this account will be able
  to use the data sources endpoint.
  

Criar uma nova fonte de dados

As fontes de dados principais são as principais fontes de dados do seu inventário do Merchant Center. Só é possível adicionar ou remover produtos usando uma fonte de dados principal. Se todos os produtos que você adicionar à sua fonte de dados principal atenderem aos requisitos de qualificação e de dados do Merchant Center, não será necessário criar mais fontes de dados.

Para criar uma nova fonte de dados principal com um feedLabel e um contentLanguage específicos, defina os campos feedLabel e contentLanguage na configuração específica do tipo. Para mais informações sobre esses campos, consulte PrimaryProductDataSource.

O exemplo de solicitação a seguir demonstra como criar uma fonte de dados de produto principal:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "primaryProductDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "feedLabel": "{FEED_LABEL}",
    "countries": [
      "{COUNTRY}"
    ],
    "channel": "ONLINE_PRODUCTS"
  }
}

Substitua:

• {ACCOUNT_ID}: o identificador exclusivo da sua conta do Merchant Center.
• {DISPLAY_NAME}: o nome de exibição da fonte de dados.
• {CONTENT_LANGUAGE}: o código de idioma ISO 639-1 de duas letras dos produtos na fonte de dados.
• {FEED_LABEL}: o rótulo do feed da fonte de dados.
• {COUNTRY}: o código de território CLDR do país de destino dos produtos que serão enviados usando a fonte de dados.

Depois que a solicitação for executada, você vai receber a seguinte resposta:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "primaryProductDataSource": {
    "channel": "ONLINE_PRODUCTS",
    "feedLabel": "{FEED_LABEL}",
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "countries": [
      "{COUNTRY}"
    ],
    "defaultRule": {
      "takeFromDataSources": [
        {
          "self": true
        }
      ]
    }
  },
  "input": "API"
}

Para mais informações sobre como criar uma fonte de dados, consulte o método accounts.dataSources.create.

Para conferir a fonte de dados recém-criada, use o método accounts.dataSources.get ou accounts.dataSources.list.

O exemplo a seguir demonstra como criar uma fonte de dados de produto principal para a combinação GB e en feedLabel e contentLanguage.

Java

     public static String createDataSource(Config config, String displayName) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String parent = getParent(config.getAccountId().toString());

    // The type of data that this datasource will receive.
    PrimaryProductDataSource primaryProductDataSource =
        PrimaryProductDataSource.newBuilder()
            // Channel can be "ONLINE_PRODUCTS" or "LOCAL_PRODUCTS" or "PRODUCTS" .
            // While accepted, datasources with channel "products" representing unified products
            // currently cannot be used with the Products bundle.
            .setChannel(PrimaryProductDataSource.Channel.ONLINE_PRODUCTS)
            .addCountries("GB")
            .build();

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      CreateDataSourceRequest request =
          CreateDataSourceRequest.newBuilder()
              .setParent(parent)
              .setDataSource(
                  DataSource.newBuilder()
                      .setDisplayName(displayName)
                      .setPrimaryProductDataSource(primaryProductDataSource)
                      .build())
              .build();

      System.out.println("Sending Create PrimaryProduct DataSource request");
      DataSource response = dataSourcesServiceClient.createDataSource(request);
      System.out.println("Created DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      // Null is necessary to satisfy the compiler as we're not returning a String on failure.
      return null;
    }
  }
CreatePrimaryProductDataSourceWildCardSample.java

Criar uma nova fonte de dados principal para segmentar vários países

Para criar um novo feed principal que ajude a segmentar vários países, configure a fonte de dados usando PrimaryProductDataSource e não defina os campos feedLabel e contentLanguage.

Ao usar a API Content for Shopping, há apenas uma fonte de dados da API criada para você. Com a API Merchant Data Sources, é possível ter várias fontes de dados de API, algumas delas sem os campos feedLabel e contentLanguage definidos.

Somente as fontes de dados com entrada de API podem estar sem os campos feedLabel e contentLanguage definidos. Esse tipo de fonte de dados não é compatível com entradas de arquivo.

Criar uma fonte de dados complementar e vincular à principal

As fontes de dados complementares são usadas apenas para atualizar dados de produtos que já existem em uma ou mais fontes de dados principais. É possível ter várias fontes de dados complementares, e cada uma delas pode complementar os dados em qualquer número de fontes de dados principais.

É possível usar origens de dados complementares para fazer atualizações parciais nos dados do produto adicionando o identificador exclusivo da origem como um parâmetro de consulta ao fazer chamadas para os métodos accounts.productInputs.insert e accounts.productInputs.delete. Só é possível usar fontes de dados complementares para atualizar produtos existentes.

Para criar uma fonte de dados complementar, configure-a usando SupplementalProductDataSource e vincule-a atualizando o campo defaultRule na fonte de dados principal.

As fontes de dados de arquivos complementares precisam ter os campos feedLabel e contentLanguage definidos. Os campos feedLabel e contentLanguage das fontes de dados de API suplementares precisam estar sempre desmarcados.

O exemplo a seguir demonstra como criar uma fonte de dados de produto suplementar de arquivo para a combinação en e GB contentLanguage e feedLabel.

Java

     private static FileInput setFileInput() {
    // If FetchSettings are not set, then this will be an `UPLOAD` file type
    // that you must manually upload via the Merchant Center UI.
    return FileInput.newBuilder()
        // FileName is required for `UPLOAD` fileInput type.
        .setFileName("British T-shirts Supplemental Data")
        .build();
  }

  public static String createDataSource(Config config, String displayName, FileInput fileInput)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String parent = getParent(config.getAccountId().toString());

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      CreateDataSourceRequest request =
          CreateDataSourceRequest.newBuilder()
              .setParent(parent)
              .setDataSource(
                  DataSource.newBuilder()
                      .setDisplayName(displayName)
                      .setSupplementalProductDataSource(
                          SupplementalProductDataSource.newBuilder()
                              .setContentLanguage("en")
                              .setFeedLabel("GB")
                              .build())
                      .setFileInput(fileInput)
                      .build())
              .build();

      System.out.println("Sending create SupplementalProduct DataSource request");
      DataSource response = dataSourcesServiceClient.createDataSource(request);
      System.out.println("Created DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      // Null is necessary to satisfy the compiler as we're not returning a String on failure.
      return null;
    }
  }
CreateFileSupplementalProductDataSourceSample.java

Para criar uma origem de dados complementar que funcione para todas as combinações de feedLabel e contentLanguage, execute o seguinte exemplo.

Java

     public static String createDataSource(Config config, String displayName) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String parent = getParent(config.getAccountId().toString());

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      CreateDataSourceRequest request =
          CreateDataSourceRequest.newBuilder()
              .setParent(parent)
              .setDataSource(
                  DataSource.newBuilder()
                      .setDisplayName(displayName)
                      .setSupplementalProductDataSource(
                          SupplementalProductDataSource.newBuilder().build())
                      .build())
              .build();

      System.out.println("Sending create SupplementalProduct DataSource request");
      DataSource response = dataSourcesServiceClient.createDataSource(request);
      System.out.println("Created DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null; // Necessary to satisfy the compiler as we're not returning a
      // String on failure.
    }
  }
CreateSupplementalProductDataSourceWildCardSample.java

Configurar uma programação para a fonte de dados de arquivos

Para configurar uma programação para o feed de arquivos, defina a fonte de dados como uma fonte de dados de arquivos usando o campo FileInput e, em seguida, configure fetchsettings usando o campo FileInput.FetchSettings.

Excluir uma fonte de dados

Para excluir uma fonte de dados da sua conta, use o método accounts.dataSources.delete.

O exemplo a seguir demonstra como usar o pacote DeleteDataSourceRequest para excluir uma fonte de dados.

Java

     public static void deleteDataSource(Config config, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String name =
        DataSourceName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setDatasource(dataSourceId)
            .build()
            .toString();

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {
      DeleteDataSourceRequest request = DeleteDataSourceRequest.newBuilder().setName(name).build();

      System.out.println("Sending deleteDataSource request");
      // Delete works for any datasource type.
      // If Type "Supplemental", delete will only work if it's not linked to any primary feed.
      // If a link exists and the Type is "Supplemental", you will need to remove the supplemental
      // feed from the default and/or custom rule(s) of any primary feed(s) that references it. Then
      // retry the delete.

      dataSourcesServiceClient.deleteDataSource(request); // No response returned on success.
      System.out.println(
          "Delete successful, note that it may take a few minutes for the delete to update in"
              + " the system.");
    } catch (Exception e) {
      System.out.println(e);
    }
  }
DeleteDataSourceSample.java

Buscar a fonte de dados

Para buscar um arquivo configurado na fonte de dados, use o método accounts.dataSources.fetch. Esse método executa a busca de dados imediatamente em uma fonte de dados da sua conta. Esse método só funciona em fontes de dados com um conjunto de entrada de arquivo.

Acessar a fonte de dados

Para recuperar a configuração da fonte de dados da sua conta, use o método accounts.dataSources.get.

O exemplo a seguir demonstra como usar o pacote GetDataSourceRequest para extrair uma fonte de dados específica de uma determinada conta do Merchant Center.

Java

     public static DataSource getDataSource(Config config, String dataSourceId) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates datasource name to identify datasource.
    String name =
        DataSourceName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setDatasource(dataSourceId)
            .build()
            .toString();

    // Calls the API and catches and prints any network failures/errors.
    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      // The name has the format: accounts/{account}/datasources/{datasource}
      GetDataSourceRequest request = GetDataSourceRequest.newBuilder().setName(name).build();

      System.out.println("Sending GET DataSource request:");
      DataSource response = dataSourcesServiceClient.getDataSource(request);

      System.out.println("Retrieved DataSource below");
      System.out.println(response);
      return response;
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null; // Necessary to satisfy the compiler as we're not returning a
      // DataSource on failure.
    }
  }
GetDataSourceSample.java

Listar a origem de dados

Para listar as configurações das fontes de dados da sua conta, use o método accounts.dataSources.list.

O exemplo a seguir demonstra como usar o pacote ListDataSourceRequest para listar todas as fontes de dados de uma determinada conta do Merchant Center.

Java

     public static ArrayList<DataSource> listDataSources(Config config) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify the account from which to list all the datasources.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      // The parent has the format: accounts/{account}
      ListDataSourcesRequest request =
          ListDataSourcesRequest.newBuilder().setParent(parent).build();

      System.out.println("Sending list datasources request:");
      ListDataSourcesPagedResponse response = dataSourcesServiceClient.listDataSources(request);

      int count = 0;
      ArrayList<DataSource> dataSources = new ArrayList<DataSource>();
      ArrayList<DataSource> justPrimaryDataSources = new ArrayList<DataSource>();

      // Iterates over all rows in all pages and prints the datasource in each row.
      // Automatically uses the `nextPageToken` if returned to fetch all pages of data.
      for (DataSource element : response.iterateAll()) {
        System.out.println(element);
        count++;
        dataSources.add(element);
        // The below lines show how to filter datasources based on type.
        // `element.hasSupplementalProductDataSource()` would give you supplemental
        // datasources, etc.
        if (element.hasPrimaryProductDataSource()) {
          justPrimaryDataSources.add(element);
        }
      }
      System.out.print("The following count of elements were returned: ");
      System.out.println(count);
      return dataSources;
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null; // Necessary to satisfy the compiler as we're not returning an
      // ArrayList<DataSource> on failure.
    }
  }
ListDataSourcesSample.java

Origem de dados do patch

Para atualizar a configuração de uma fonte de dados, use o método accounts.dataSources.patch.

O exemplo a seguir demonstra como usar o pacote UpdateDataSourceRequest para atualizar uma fonte de dados. Também demonstra como atualizar uma origem de dados principal para adicionar origens de dados complementares à regra padrão.

Java

     public static String updateDataSource(Config config, String displayName, String dataSourceId)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates datasource name to identify datasource.
    String name =
        DataSourceName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setDatasource(dataSourceId)
            .build()
            .toString();

    DataSource dataSource =
        DataSource.newBuilder()
            // Update the datasource to have the new display name
            .setDisplayName(displayName)
            .setName(name)
            .build();

    FieldMask fieldMask = FieldMask.newBuilder().addPaths("display_name").build();

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      UpdateDataSourceRequest request =
          UpdateDataSourceRequest.newBuilder()
              .setDataSource(dataSource)
              .setUpdateMask(fieldMask)
              .build();

      System.out.println("Sending Update DataSource request");
      DataSource response = dataSourcesServiceClient.updateDataSource(request);
      System.out.println("Updated DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null;
    }
  }

  public String updateDataSource(
      Config config,
      String primaryDataSourceName,
      String firstSupplementalDataSourceName,
      String secondSupplementalDataSourceName)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Setting self to 'true' refers to the primary datasource itself.
    DataSourceReference dataSourceReferenceSelf =
        DataSourceReference.newBuilder().setSelf(true).build();
    DataSourceReference firstSupplementalDataSourceReference =
        DataSourceReference.newBuilder()
            .setSupplementalDataSourceName(firstSupplementalDataSourceName)
            .build();
    DataSourceReference secondSupplementalDataSourceReference =
        DataSourceReference.newBuilder()
            .setSupplementalDataSourceName(secondSupplementalDataSourceName)
            .build();

    // The attributes will first be taken from the primary DataSource.
    // Then the first supplemental DataSource if the attribute is not in the primary DataSource
    // And finally the second supplemental DataSource if not in the first two DataSources.
    // Note that CustomRules could change the behavior of how updates are applied.
    DefaultRule defaultRule =
        DefaultRule.newBuilder()
            .addTakeFromDataSources(dataSourceReferenceSelf)
            .addTakeFromDataSources(firstSupplementalDataSourceReference)
            .addTakeFromDataSources(secondSupplementalDataSourceReference)
            .build();

    // The type of data that this datasource will receive.
    PrimaryProductDataSource primaryProductDataSource =
        PrimaryProductDataSource.newBuilder().setDefaultRule(defaultRule).build();

    DataSource dataSource =
        DataSource.newBuilder()
            // Update the primary datasource to have the default rule datasources in the correct
            // order.
            .setPrimaryProductDataSource(primaryProductDataSource)
            .setName(primaryDataSourceName)
            .build();

    // The '.' signifies a nested field.
    FieldMask fieldMask =
        FieldMask.newBuilder().addPaths("primary_product_data_source.default_rule").build();

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      UpdateDataSourceRequest request =
          UpdateDataSourceRequest.newBuilder()
              .setDataSource(dataSource)
              .setUpdateMask(fieldMask)
              .build();

      System.out.println("Sending Update DataSource request");
      DataSource response = dataSourcesServiceClient.updateDataSource(request);
      System.out.println("Updated DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null;
    }
  }
UpdateDataSourceSample.java

Vincular origens de dados

As fontes de dados de produtos principais permitem gerenciar a regra padrão das fontes de dados. A regra padrão é aquela que se aplica a todos os atributos na sua fonte de dados. A regra padrão pode ser definida ao criar a origem de dados ou atualizando uma origem de dados existente pelo campo de regra padrão.

Para mais informações sobre como configurar regras, consulte Configurar regras para suas fontes de dados de produtos.

O exemplo de configuração a seguir garante que todos os atributos sejam primeiro retirados da fonte de dados com o identificador exclusivo 1001. Em seguida, os atributos ausentes são adicionados da fonte de dados principal. Eventualmente, os atributos restantes serão retirados da fonte de dados suplementar com o identificador exclusivo 1002, se não tiverem sido fornecidos em nenhuma outra fonte de dados. Se o mesmo atributo for fornecido em várias fontes de dados, o valor mais alto da lista será selecionado.

defaultRule {
 takeFromDataSources: [
   '1001', // Supplemental product data source
   'self', //  Self reference to the primary data source
   '1002' // Supplemental product data source
 ]
}

Observação: as regras personalizadas não podem ser modificadas pela API.

Gerenciamento automático de feeds

Para inscrever sua conta no gerenciamento automático de origens de dados, faça o seguinte:

• Para verificar se a sua conta está qualificada para inscrição, chame o método accounts.autofeedSettings.getAutofeedSettings.
• Verifique se a conta não é uma conta de marketplace.

Depois que sua conta estiver qualificada para inscrição, você poderá usar o método accounts.autofeedSettings.updateAutofeedSettings para ativar o gerenciamento automático de fontes de dados. Ativar o gerenciamento automático de origens de dados permite que o Google adicione automaticamente os produtos da sua loja on-line e garanta que eles estejam sempre atualizados nas plataformas do Google.

Recuperar o status do upload de arquivo

Para conferir o status de uma fonte de dados com um arquivo, busca ou planilha, chame o método GET do serviço accounts.dataSources.fileUploads. Para receber o resultado da última recuperação da fonte de dados computada de forma assíncrona quando o processamento da fonte de dados for concluído, use o identificador de nome latest.

GET https://merchantapi.googleapis.com/accounts/v1beta/{ACCOUNT_ID}/datasources/{DATASOURCE_ID}/fileUploads/latest

O status do upload de arquivos pode conter uma visualização detalhada dos seus produtos, incluindo possíveis problemas.

O status de upload do arquivo pode não existir se ele nunca foi enviado. O status de upload do arquivo pode estar em processamento se solicitado logo após o upload.