مراجعة المنتجات باستخدام Merchant API

مراجعات المنتجات هي جزء مهم من تجربة التسوّق للعملاء. تساعد هذه التقييمات والمراجعات العملاء في البحث عن المنتجات واتّخاذ قرارات الشراء. يمكن أن تجذب المراجعات الإيجابية للمنتجات المزيد من العملاء المؤهّلين إلى صفحات منتجات البائع. وتشمل المصادر البائعين ومجمِّعي المراجعات ومواقع المراجعات ومستخدمي Google.

توضّح هذه الصفحة كيفية إدارة مراجعات المنتجات باستخدام Merchant API.

المتطلبات الأساسية

تحتاج Google إلى تقديم معلومات محدّدة. يجب توفّر ما يلي:

  • خلاصة مراجعات منتجات نشطة في Google Merchant Center
  • يجب أن يكون حسابك مسجّلاً في برنامج "تقييمات المنتج". يمكنك التحقّق من الأهلية آليًا باستخدام واجهة Programs sub-API أو من خلال Merchant Center. إذا لم تكن غير مؤهّل، يمكنك الاطّلاع على مزيد من المعلومات حول التسجيل في برنامج "تقييمات المنتج".
  • لمراجعة المنتجات باستخدام Merchant API، أرسِل طلبًا لإدراجها في القائمة المسموح بها في نموذج الدعم الخاص بـ Shopping API ضمن "ما هي المشكلة/السؤال؟"

إنشاء مصدر بيانات

استخدِم طريقة datasource.create لإنشاء خلاصة مراجعات المنتجات. إذا كانت هناك خلاصة حالية لمراجعات المنتجات أو التجار، استخدِم accounts.dataSources.list لجلب accounts.dataSources.name. احفظ اسم مصدر البيانات الذي أنشأته أو استرجِعه في قاعدة بياناتك المحلية لكل مراجعة. يكون شكل الطلب على النحو التالي:

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

مثال

يعرض المثال طلبًا واستجابة نموذجيين:

الطلب

POST https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources
{
  "displayName": "My API Data Source",
  "primaryProductDataSource": {}
}

الردّ

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "My API Data Source",
  "primaryProductDataSource": {},
  "input": "API"
}

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء مصدر بيانات لمراجعات المنتجات.

إنشاء مراجعة لمنتج

يمكنك استخدام طريقة accounts.productreviews.insert لإنشاء مراجعة منتج أو تعديلها. تتطلّب طريقة accounts.productreviews.insert إدخال مورد productreview واسم مصدر بيانات. وتعرض السمة productreview الجديدة أو المعدَّلة، في حال نجاح العملية. لإنشاء مراجعة لمنتج، يجب أن يكون لديك datasource.name.

شكل الطلب:

POST https://merchantapi.googleapis.com/reviews/v1/{parent=accounts/{ACCOUNT_ID}/}productReviews:insert

يوضّح نموذج الطلب التالي كيفية إنشاء مراجعة منتج.

POST https://merchantapi.googleapis.com/reviews/v1/accounts/{ACCOUNT_ID}/productReviews:insert?dataSource=accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}

  productReviewId = 'my_product_review'
  productReviewAttributes {
    aggregatorName = 'aggregator_name'
    subclientName = 'subclient_name'
    publisherName = 'publisher_name'
    publisherFavicon = 'https://www.google.com/favicon.ico'
    reviewerId = 'reviewer_id'
    reviewerIsAnonymous = false
    reviewerUsername = 'reviewer_username'
    reviewLanguage = 'en'
    reviewCountry = 'US'
    reviewTime = '2024-04-01T00:00:00Z'
    title = 'Incredible product'
    content = 'This is an incredible product.'
    pros = ['pro1', 'pro2']
    cons = ['con1', 'con2']
    reviewLink = {
      type = 'SINGLETON'
      link = 'https://www.google.com'
    }
    reviewerImageLinks = ['https://www.google.com/reviewer.png']
    minRating = 1
    maxRating = 10
    rating = 8.5
    productNames = ['product_name']
    productLinks = ['https://www.google.com/product']
    asins = ['asin1', 'asin2']
    gtins = ['gtin1', 'gtin2']
    mpns = ['mpn1', 'mpn2']
    skus = ['sku1', 'sku2']
    brands = ['brand1', 'brand2']
    isSpam = false
    collectionMethod = 'POST_FULFILLMENT'
    transactionId = 'transaction_id'
  }

بعد إنشاء مراجعة المنتج، قد يستغرق نشرها بضع دقائق.

في ما يلي نموذج يمكنك استخدامه لإدراج مراجعات منتجات متعددة بشكل غير متزامن:

جافا

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.reviews.v1.InsertProductReviewRequest;
import com.google.shopping.merchant.reviews.v1.ProductReview;
import com.google.shopping.merchant.reviews.v1.ProductReviewAttributes;
import com.google.shopping.merchant.reviews.v1.ProductReviewAttributes.ReviewLink;
import com.google.shopping.merchant.reviews.v1.ProductReviewAttributes.ReviewLink.Type;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceClient;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple product reviews asynchronously. */
public class InsertProductReviewsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  // Returns a product review with a random ID.
  private static ProductReview createProductReview(String accountId) {
    // MAKE SURE YOU PASS AN ACTUAL PRODUCT REVIEW ID HERE.
    String productReviewId = generateRandomString();

    ProductReviewAttributes attributes =
        ProductReviewAttributes.newBuilder()
            .setTitle("Would not recommend!")
            .setContent("Not fantastic.")
            .setMinRating(1)
            .setMaxRating(5)
            .setRating(2)
            .setReviewTime(Timestamp.newBuilder().setSeconds(123456789).build())
            .addProductLinks("exampleproducturl.com")
            .setReviewLink(
                ReviewLink.newBuilder()
                    .setLink("examplereviewurl.com")
                    // The review page contains only this single review.
                    .setType(Type.SINGLETON)
                    .build())
            .addGtins("9780007350896")
            .addGtins("9780007350897")
            .build();

    return ProductReview.newBuilder()
        .setProductReviewId(productReviewId)
        .setProductReviewAttributes(attributes)
        .build();
  }

  public static void asyncInsertProductReviews(String accountId, String dataSourceId)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    ProductReviewsServiceSettings productReviewsServiceSettings =
        ProductReviewsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (ProductReviewsServiceClient productReviewsServiceClient =
        ProductReviewsServiceClient.create(productReviewsServiceSettings)) {

      // Arbitrarily creates five product reviews with random IDs.
      List<InsertProductReviewRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertProductReviewRequest request =
            InsertProductReviewRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setProductReview(createProductReview(accountId))
                // Must be a product reviews data source. In other words, a data source whose "type"
                // is ProductReviewDataSource.
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the product reviews.
      List<ApiFuture<ProductReview>> futures =
          requests.stream()
              .map(
                  request ->
                      productReviewsServiceClient.insertProductReviewCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<ProductReview>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<ProductReview>>() {
            @Override
            public void onSuccess(List<ProductReview> results) {
              System.out.println("Inserted product reviews below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertProductReviews(config.getAccountId().toString(), "YOUR_DATA_SOURCE_ID");
  }
}

استرداد مراجعة منتج

للاطّلاع على مراجعة منتج، استخدِم accounts.productreviews.get. هذا الملف متاح للقراءة فقط. يتطلّب ذلك إدخال accountId ورقم تعريف مراجعة المنتج كجزء من حقل الاسم. تعرض طريقة GET مرجع مراجعة المنتج المقابل.

GET https://merchantapi.googleapis.com/reviews/v1/{name=accounts/{ACCOUNT_ID}/productReviews/*}

في ما يلي نموذج يمكنك استخدامه لاسترداد مراجعة منتج:

جافا

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.reviews.v1.GetProductReviewRequest;
import com.google.shopping.merchant.reviews.v1.ProductReview;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceClient;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to get a product review. */
public class GetProductReviewSample {

  public static void getProductReview(String accountId, String productReviewId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    ProductReviewsServiceSettings productReviewsServiceSettings =
        ProductReviewsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (ProductReviewsServiceClient productReviewsServiceClient =
        ProductReviewsServiceClient.create(productReviewsServiceSettings)) {

      GetProductReviewRequest request =
          GetProductReviewRequest.newBuilder()
              .setName(String.format("accounts/%s/productReviews/%s", accountId, productReviewId))
              .build();

      System.out.println("Sending get product review request:");
      ProductReview response = productReviewsServiceClient.getProductReview(request);
      System.out.println("Product review retrieved successfully:");
      System.out.println(response.getName());
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    String productReviewId = "YOUR_PRODUCT_REVIEW_ID";
    getProductReview(config.getAccountId().toString(), productReviewId);
  }
}

عرض مراجعات المنتجات

يمكنك استخدام طريقة productreviews.list لعرض جميع مراجعات المنتجات التي تم إنشاؤها.

GET https://merchantapi.googleapis.com/reviews/v1/{parent=accounts/{ACCOUNT_ID}}/productReviews

في ما يلي نموذج يمكنك استخدامه لإدراج جميع المراجعات لمنتج معيّن:

جافا

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.reviews.v1.ListProductReviewsRequest;
import com.google.shopping.merchant.reviews.v1.ProductReview;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceClient;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceClient.ListProductReviewsPagedResponse;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to list all the product reviews in a given account. */
public class ListProductReviewsSample {

  public static void listProductReviews(String accountId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    ProductReviewsServiceSettings productReviewsServiceSettings =
        ProductReviewsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (ProductReviewsServiceClient productReviewsServiceClient =
        ProductReviewsServiceClient.create(productReviewsServiceSettings)) {

      ListProductReviewsRequest request =
          ListProductReviewsRequest.newBuilder()
              .setParent(String.format("accounts/%s", accountId))
              .build();

      System.out.println("Sending list product reviews request:");
      ListProductReviewsPagedResponse response =
          productReviewsServiceClient.listProductReviews(request);

      int count = 0;

      // Iterates over all rows in all pages and prints all product reviews.
      for (ProductReview element : response.iterateAll()) {
        System.out.println(element);
        count++;
      }
      System.out.print("The following count of elements were returned: ");
      System.out.println(count);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    listProductReviews(config.getAccountId().toString());
  }
}

حذف مراجعات المنتجات

لحذف مراجعة منتج، استخدِم accounts.productreviews.delete. على غرار طريقة GET، تتطلّب هذه الطريقة حقل الاسم لمراجعة المنتج التي تم عرضها أثناء الإنشاء.

DELETE https://merchantapi.googleapis.com/reviews/v1/{name=accounts/{ACCOUNT_ID}/productReviews/*}

في ما يلي نموذج يمكنك استخدامه لحذف مراجعة منتج:

جافا

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.reviews.v1.DeleteProductReviewRequest;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceClient;
import com.google.shopping.merchant.reviews.v1.ProductReviewsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to delete a product review. */
public class DeleteProductReviewSample {

  public static void deleteProductReview(String accountId, String productReviewId)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    ProductReviewsServiceSettings productReviewsServiceSettings =
        ProductReviewsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (ProductReviewsServiceClient productReviewsServiceClient =
        ProductReviewsServiceClient.create(productReviewsServiceSettings)) {

      DeleteProductReviewRequest request =
          DeleteProductReviewRequest.newBuilder()
              .setName(String.format("accounts/%s/productReviews/%s", accountId, productReviewId))
              .build();

      System.out.println("Sending delete product review request:");
      productReviewsServiceClient.deleteProductReview(request);
      System.out.println("Product review deleted successfully");
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    String productReviewId = "YOUR_PRODUCT_REVIEW_ID";
    deleteProductReview(config.getAccountId().toString(), productReviewId);
  }
}

حالة مراجعة المنتج

يحتوي مصدر مراجعة المنتج على الحالة المشابهة لواجهات برمجة التطبيقات الأخرى، وهو جزء لا يتجزأ من المصدر ويتّبع بنية المشكلة والوجهة نفسها.