Présentation de l'API Merchant Data Source

Cette page explique comment créer et mettre à jour de manière programmatique vos sources de données qui vous permettent d'insérer des produits. Les sources de données automatiques facilitent l'envoi de vos données produit à Google. Les sources de données automatisées permettent de s'assurer que les informations les plus récentes sur les produits pertinents de votre site Web parviennent à Google.

Content API for Shopping ne vous permet de créer que des sources de données principales. Avec l'API Merchant Data Sources, vous pouvez créer les types de sources de données suivants:

Content API for Shopping ne vous permet de gérer les sources de données que par importation de fichiers. L'API Merchant vous permet de gérer des sources de données à l'aide d'entrées de fichiers et d'API.

L'API Merchant Data sources vous permet d'effectuer les opérations suivantes:

  • Créez une source de données principale avec un feedLabel et un contentLanguage spécifiques.
  • Créez une source de données pour laquelle les champs feedLabel et contentLanguage ne sont pas définis. Avec ce type de source de données, vous pouvez cibler plusieurs pays pour vos produits, car vous pouvez insérer des produits avec différentes combinaisons de feedLabel et de contentLanguage dans une seule source de données.
  • Créez une source de données supplémentaire à associer à une source de données principale existante.
  • Configurez un planning pour une source de données de fichier.
  • Inscrivez votre compte pour la gestion automatique des sources de données.
  • Gérer les sources de données de l'API
  • Gérez la règle par défaut des sources de données à l'aide de sources de données produit principales.
  • Utiliser d'autres types de sources de données, comme les promotions

Vous ne pouvez pas utiliser l'API Merchant pour insérer des produits dans une source de données contenant à la fois des produits en magasin et en ligne. Pour en savoir plus sur les canaux de sources de données, consultez la section Canaux.

Prérequis

  • Votre compte doit avoir été migré vers des flux pour une seule langue.
  • Pour vérifier que le compte est déjà migré vers la répartition des cibles de données, utilisez la liste des sources de données ou les méthodes get. Si vous n'êtes pas éligible, vous recevrez le message d'exception suivant et vous devrez contacter l'assistance.

    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.
    

Créer une source de données

Les sources de données principales sont les principales sources de données de votre inventaire Merchant Center. Vous ne pouvez ajouter ni supprimer des produits qu'à l'aide d'une source de données principale. Si tous les produits que vous ajoutez à votre source de données principale respectent les conditions et les exigences concernant les données de Merchant Center, vous n'avez pas besoin de créer d'autres sources de données.

Pour créer une source de données principale avec des feedLabel et contentLanguage spécifiques, définissez les champs feedLabel et contentLanguage dans la configuration spécifique au type. Pour en savoir plus sur ces champs, consultez PrimaryProductDataSource.

L'exemple de requête suivant montre comment créer une source de données produit principale:

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

Remplacez les éléments suivants :

  • {ACCOUNT_ID}: identifiant unique de votre compte Merchant Center.
  • {DISPLAY_NAME}: nom à afficher de la source de données.
  • {CONTENT_LANGUAGE}: code de langue ISO 639-1 à deux lettres des produits de la source de données.
  • {FEED_LABEL}: libellé du flux de la source de données.
  • {COUNTRY}: code de territoire CLDR du pays cible des produits qui seront importés à l'aide de la source de données.

Une fois la requête exécutée, la réponse suivante s'affiche:

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

Pour en savoir plus sur la création d'une source de données, consultez la méthode accounts.dataSources.create.

Pour afficher votre nouvelle source de données, utilisez la méthode accounts.dataSources.get ou accounts.dataSources.list.

L'exemple suivant montre comment créer une source de données produit principale pour la combinaison GB et en feedLabel et 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;
    }
  }

Créer une source de données principale qui permet de cibler plusieurs pays

Pour créer un flux principal qui vous aide à cibler plusieurs pays, configurez votre source de données à l'aide de PrimaryProductDataSource et ne définissez pas les champs feedLabel et contentLanguage.

Avec Content API for Shopping, une seule source de données API est créée pour vous. L'API Merchant Data sources vous permet de disposer de plusieurs sources de données API, dont certaines peuvent ne pas avoir de champs feedLabel et contentLanguage définis.

Seules les sources de données avec entrée API peuvent être définies sans les champs feedLabel et contentLanguage. Ce type de sources de données n'est pas compatible avec les entrées de fichiers.

Créer une source de données supplémentaire et l'associer à la source de données principale

Les sources de données supplémentaires ne doivent être utilisées que pour mettre à jour les données produit déjà présentes dans un ou plusieurs flux principaux. Vous pouvez avoir plusieurs sources de données supplémentaires, chacune pouvant compléter les données de différents flux principaux.

Vous pouvez utiliser des sources de données supplémentaires pour effectuer des mises à jour partielles des données produit en ajoutant l'identifiant unique de la source de données comme paramètre de requête lorsque vous appelez les méthodes accounts.productInputs.insert et accounts.productInputs.delete. Vous ne pouvez utiliser des sources de données supplémentaires que pour mettre à jour des produits existants.

Pour créer une source de données supplémentaire, configurez votre source de données à l'aide de SupplementalProductDataSource, puis associez-la en mettant à jour le champ defaultRule de votre source de données principale.

Les champs feedLabel et contentLanguage doivent être définis pour les sources de données de fichiers supplémentaires. Les champs feedLabel et contentLanguage doivent toujours être définis sur "unset" pour les sources de données API supplémentaires.

L'exemple suivant montre comment créer une source de données de produits complémentaires de fichier pour la combinaison en et GB contentLanguage et 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;
    }
  }

Pour créer une source de données complémentaire qui fonctionne pour toutes les combinaisons feedLabel et contentLanguage, exécutez l'exemple suivant.

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

Configurer un planning pour votre source de données de fichiers

Pour configurer un calendrier pour votre flux de fichiers, configurez votre source de données en tant que source de données de fichiers à l'aide du champ FileInput, puis configurez fetchsettings à l'aide du champ FileInput.FetchSettings.

Supprimer une source de données

Pour supprimer une source de données existante de votre compte, utilisez la méthode accounts.dataSources.delete.

L'exemple suivant montre comment utiliser le package DeleteDataSourceRequest pour supprimer une source de données.

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);
    }
  }

Source de données de récupération

Pour extraire un fichier configuré dans la source de données, utilisez la méthode accounts.dataSources.fetch. Cette méthode effectue l'extraction de données immédiatement sur une source de données de votre compte. Cette méthode ne fonctionne que sur les sources de données pour lesquelles une entrée de fichier est définie.

Obtenir la source de données

Pour récupérer la configuration de la source de données de votre compte, utilisez la méthode accounts.dataSources.get.

L'exemple suivant montre comment utiliser le package GetDataSourceRequest pour récupérer une source de données spécifique pour un compte Merchant Center donné.

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

Source de données de la liste

Pour répertorier les configurations des sources de données de votre compte, utilisez la méthode accounts.dataSources.list.

L'exemple suivant montre comment utiliser le package ListDataSourceRequest pour lister toutes les sources de données d'un compte Merchant Center donné.

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

Source de données de correctif

Pour mettre à jour la configuration d'une source de données existante, utilisez la méthode accounts.dataSources.patch.

L'exemple suivant montre comment utiliser le package UpdateDataSourceRequest pour mettre à jour une source de données. Il montre également comment mettre à jour une source de données principale pour ajouter des sources de données supplémentaires à sa règle par défaut.

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

Les sources de données produit principales vous permettent de gérer la règle par défaut des sources de données. La règle par défaut s'applique à tous les attributs de votre source de données. La règle par défaut peut être définie lors de la création de la source de données ou en mettant à jour une source de données existante via le champ de règle par défaut.

Pour en savoir plus sur la configuration de règles, consultez Configurer des règles pour vos sources de données produit.

L'exemple de configuration suivant garantit que tous les attributs sont d'abord extraits de la source de données avec l'identifiant unique 1001. Les attributs manquants sont ensuite ajoutés à partir de la source de données principale. À terme, les attributs restants seront extraits de la source de données supplémentaire avec l'identifiant unique 1002, s'ils ne sont pas déjà fournis dans une autre source de données. Si le même attribut est fourni dans plusieurs sources de données, la valeur la plus élevée de la liste est sélectionnée.

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

Gestion automatique des flux

Pour enregistrer votre compte pour la gestion automatique des sources de données, procédez comme suit:

Une fois que votre compte est éligible à l'inscription, vous pouvez utiliser la méthode accounts.autofeedSettings.updateAutofeedSettings pour activer la gestion automatique des sources de données. En activant la gestion automatique des sources de données, vous autorisez Google à ajouter automatiquement vos produits à partir de votre boutique en ligne et à vous assurer qu'ils sont toujours à jour sur les plates-formes de Google.

Récupérer l'état de l'importation de fichiers

Pour obtenir l'état d'une source de données avec un fichier, une récupération ou une feuille de calcul, vous pouvez appeler la méthode GET du service accounts.dataSources.fileUploads. Pour obtenir le résultat de la dernière récupération de la source de données calculée de manière asynchrone lorsque le traitement de la source de données est terminé, utilisez l'identifiant de nom latest.

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

L'état de l'importation du fichier peut contenir une vue détaillée de vos produits, y compris les problèmes potentiels.

Notez que l'état de l'importation du fichier peut ne pas exister si le fichier n'a jamais été importé. L'état de l'importation du fichier peut être "En cours de traitement" si la demande est effectuée peu de temps après l'importation du fichier.