تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

نظرة عامة على Merchant Products API

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

تحتوي Merchant Products API على موردَين.

يمثّل الرمز productInputs أجزاء الإدخال في منتجاتك.
يمثّل products المنتجات التي تمّت معالجتها والتي تم إنشاؤها من أجزاء الإدخال.

يمكن أن يكون productInputs أساسيًا وتكميليًا، وذلك حسب ما إذا كان يتم تحميله إلى مصدر بيانات أساسي أو مصدر بيانات تكميلي. سيتم إنشاء كل product من productInput أساسي واحد وأي عدد من productInputs التكميلية.

يمكنك استخدام Merchant Products API لإنشاء كتالوجات متاجر على الإنترنت أو في المتاجر المحلية، وهي منتجات يمكن أن تظهر في وجهات تسوّق متعدّدة. يمكنك استخدام مرجع productInputs بعد إنشاء حسابك على Merchant Center وإعداد مصدر البيانات الأول وقبل تحميل مجموعة أولية من المنتجات من خلال واجهة برمجة التطبيقات.

على الرغم من أنّ التجّار يمكنهم تحميل المنتجات باستخدام ملف يُعرف باسم PrimaryProductDataSource، تتوفر عدة مزايا لإنشاء المنتجات وحذفها باستخدام Merchant API. وتشمل هذه المزايا وقت استجابة أسرع وإمكانية تعديل المنتجات في الوقت الفعلي، بدون الحاجة إلى إدارة ملفات كبيرة. قد يستغرق ظهور التغييرات التي تم إجراؤها على المنتجات من خلال طلبات البيانات من واجهة برمجة التطبيقات في قاعدة بيانات Shopping ما يصل إلى عدة ساعات.

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

إذا لم يكن لديك مصدر بيانات، أنشئ مصدر بيانات باستخدام Merchant Data Sources API أو Merchant Center.

إذا كان لديك مصدر بيانات أنشأته باستخدام واجهة مستخدم Merchant Center أو باستخدام واجهة برمجة التطبيقات، يمكنك استخدام Merchant Products API لإضافة منتجاتك. إذا كنت تستخدِم Content API for Shopping لإضافة منتجات، راجِع دليل نقل البيانات للتعرّف على كيفية البدء باستخدام Merchant Products API.

أنت المسؤول عن الالتزام بسياسات إعلانات Shopping و البيانات المجانية. تحتفظ إعلانات Shopping بالحق في فرض هذه السياسات والردّ عليها بشكل مناسب إذا رصدنا محتوًى أو سلوكًا ينتهكان هذه السياسات.

الموارد

يتيح لك المرجع products استرداد معلومات المنتجات من قاعدة بيانات Shopping.

يمثّل productInput المصدر بيانات الإدخال التي ترسلها لمنتج معيّن. وتوفّر هذه الطريقة أيضًا طرقًا تتيح لك تعديل معلومات المنتجات أو حذفها واحدة تلو الأخرى أو حذف العديد منها في الوقت نفسه في وضع الحِزم. يجب أن يحتوي مرجع productInput على الحقول التالية:

channel: القناة التي ينتمي إليها المنتج
‫offerId: المعرّف الفريد للمنتج
‫contentLanguage: رمز اللغة المكوَّن من حرفَين وفقًا لمعيار ISO 639-1 للمنتجات
‫feedLabel: التصنيف الذي يتيح لك تصنيف منتجاتك والتعرّف عليها الحد الأقصى لعدد الأحرف المسموح به هو 20 حرفًا، والأحرف المسموح بها هي A-Z و0-9 والواصلة والشرطة السفلية. يجب ألا يتضمّن تصنيف الخلاصة أي مسافات. لمزيد من المعلومات، اطّلِع على استخدام تصنيفات الخلاصة.

تحميل بيانات منتج إلى حسابك

لتحميل إدخال منتج إلى حسابك، استخدِم أسلوب accounts.productInputs.insert. يجب إدخال المعرّف الفريد لمصدر البيانات الأساسي أو المصدر الإضافي.

يوضّح نموذج الطلب التالي كيفية استخدام الوسيطة accounts.productInputs.insert لتحميل إدخال منتج إلى حسابك على Merchant Center. يحدِّد الطلب سعر الشحن والمنطقة، ويقوم بضبط سمات مخصّصة، مثل تاريخ التصنيع والحجم.

POST https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE}

{
  "name": "{PRODUCT_TITLE}",
  "versionNumber": {VERSION_NUMBER},
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "offerId": "{OFFER_ID}",
  "channel": "ONLINE",
  "attributes": {
    "availability": "in stock",
    "imageLink": "{IMAGE_LINK}",
    "link": "{PRODUCT_LINK}",
    "brand": "{BRAND_NAME}",
    "price": {
      "currencyCode": "{CURRENCY_CODE}",
      "amountMicros": {PRICE}
    },
    "color": "red",
    "productWeight": {
      "value": 320,
      "unit": "g"
    },
    "adult": false,
    "shipping": [
      {
        "country": "GB",
        "price": {
          "amountMicros": {SHIPPING_COST},
          "currencyCode": "{CURRENCY_CODE_SHIPPING}"
        },
        "postalCode": "{SHIPPING_POSTALCODE}",
        "service": "",
        "region": "{SHIPPING_REGION}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}"
      }
    ],
    "gender": "Female"
  },
  "customAttributes": [
    {
      "name": "size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

غيِّر القيم في السلسلة على الشكل التالي:

{ACCOUNT_ID}: المعرّف الفريد لحسابك على Merchant Center.
{DATASOURCE}: المعرّف الفريد لمصدر البيانات. يجب أن يكون بالتنسيق accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}.
‫{PRODUCT_TITLE}: اسم المنتج
{VERSION_NUMBER}: رقم إصدار المنتج اختيارية:
‫{CONTENT_LANGUAGE}: رمز اللغة المكوّن من حرفَين وفقًا لمعيار ‎"ISO 639-1" للمنتج. مطلوب.
‫{FEED_LABEL}: التصنيف الذي يتيح لك تصنيف منتجاتك وتحديدها الحد الأقصى لعدد الأحرف المسموح به هو 20 حرفًا، وتكون الأحرف المسموح بها هي A-Z و0-9 والواصلة والشرطة السفلية. يجب ألا يتضمّن تصنيف الخلاصة أي مسافات.
‫{OFFER_ID}: المعرّف الفريد للمنتج مطلوب.
{IMAGE_LINK}: رابط صورة المنتج على موقعك الإلكتروني اختيارية:
{PRODUCT_LINK}: رابط المنتج على موقعك الإلكتروني اختيارية:
‫{CURRENCY_CODE}: تحدّد هذه السمة العملة المستخدمة للسعر باستخدام اختصارات مكوّنة من ثلاثة أحرف وفقًا لمعيار ISO 4217. اختيارية:
‫{PRICE}: سعر المنتج ممثّلاً كصعد رقمي بالفئات الصغيرة للعملة اختيارية:
{SHIPPING_COST}: سعر الشحن الثابت ممثّلاً برقم. اختيارية:
{SHIPPING_POSTALCODE}: نطاق الرمز البريدي الذي ينطبق عليه تعرفة الشحن. اختيارية:
{MAX_HANDLING_TIME}: الحدّ الأقصى لوقت المناولة بال أيام العمل بين وقت استلام الطلب ووقت شحنه. اختيارية:
{MIN_HANDLING_TIME}: الحد الأدنى لوقت المناولة بال أيام العمل بين وقت استلام الطلب ووقت شحنه. تشير القيمة 0 إلى أنّه يتم تسليم الطلب في اليوم نفسه الذي يتم استلامه فيه. اختيارية:
{MAX_TRANSIT_TIME}: الحد الأقصى لمدة النقل بالأيام العمل بين وقت شحن الطلب ووقت تسليمه اختيارية:
{MIN_TRANSIT_TIME}: الحد الأدنى لمدة النقل بال أيام العمل بين وقت شحن الطلب ووقت تسليمه تشير القيمة 0 إلى أنّه يتم تسليم الطلب في اليوم نفسه الذي يتم فيه شحنه. اختيارية:

عند تنفيذ الطلب بنجاح، يظهر الردّ التالي:

{
  "name": "{PRODUCT_NAME}",
  "product": "{PRODUCT_ID}",
  "channel": "ONLINE",
  "offerId": "{OFFER_ID}",
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "versionNumber": "{VERSION_NUMBER}",
  "attributes": {
    "link": "{PRODUCT_LINK}",
    "imageLink": "{IMAGE_LINK}",
    "adult": false,
    "availability": "in stock",
    "brand": "{BRAND_NAME}",
    "color": "red",
    "gender": "Female",
    "price": {
      "amountMicros": "{PRICE}",
      "currencyCode": "{CURRENCY_CODE}"
    },
    "shipping": [
      {
        "price": {
          "amountMicros": "{SHIPPING_COST}",
          "currencyCode": "{CURRENCY_CODE}"
        },
        "country": "{SHIPPING_COUNTRY}",
        "region": "{SHIPPING_REGION}",
        "postalCode": "{SHIPPING_POSTALCODE}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}"
      }
    ],
    "productWeight": {
      "value": 320,
      "unit": "g"
    }
  },
  "customAttributes": [
    {
      "name": "Size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

لإضافة منتج إلى حسابك على Merchant Center، يمكنك استخدام الطريقة التالية: google.shopping.merchant.accounts.v1beta.InsertProductInputSample ، كما هو موضّح في العيّنة التالية.

Java

  public static void insertProductInput(Config config, String dataSource) throws Exception {

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

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

    // Creates parent to identify where to insert the product.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (ProductInputsServiceClient productInputsServiceClient =
        ProductInputsServiceClient.create(productInputsServiceSettings)) {

      // Price to be used for shipping ($33.45).
      Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();

      Shipping shipping =
          Shipping.newBuilder()
              .setPrice(price)
              .setCountry("GB")
              .setService("1st class post")
              .build();

      Shipping shipping2 =
          Shipping.newBuilder()
              .setPrice(price)
              .setCountry("FR")
              .setService("1st class post")
              .build();

      Attributes attributes =
          Attributes.newBuilder()
              .setTitle("A Tale of Two Cities")
              .setDescription("A classic novel about the French Revolution")
              .setLink("https://exampleWebsite.com/tale-of-two-cities.html")
              .setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
              .setAvailability("in stock")
              .setCondition("new")
              .setGoogleProductCategory("Media > Books")
              .setGtin(0, "9780007350896")
              .addShipping(shipping)
              .addShipping(shipping2)
              .build();

      // The datasource can be either a primary or supplemental datasource.
      InsertProductInputRequest request =
          InsertProductInputRequest.newBuilder()
              .setParent(parent)
              // You can only insert products into datasource types of Input "API" and "FILE", and
              // of Type "Primary" or "Supplemental."
              // This field takes the `name` field of the datasource.
              .setDataSource(dataSource)
              // If this product is already owned by another datasource, when re-inserting, the
              // new datasource will take ownership of the product.
              .setProductInput(
                  ProductInput.newBuilder()
                      .setChannel(ChannelEnum.ONLINE)
                      .setContentLanguage("en")
                      .setFeedLabel("label")
                      .setOfferId("sku123")
                      .setAttributes(attributes)
                      .build())
              .build();

      System.out.println("Sending insert ProductInput request");
      ProductInput response = productInputsServiceClient.insertProductInput(request);
      System.out.println("Inserted ProductInput Name below");
      // The last part of the product name will be the product ID assigned to a product by Google.
      // Product ID has the format `channel~contentLanguage~feedLabel~offerId`
      System.out.println(response.getName());
      System.out.println("Inserted Product Name below");
      System.out.println(response.getProduct());
    } catch (Exception e) {
      System.out.println(e);
    }
  }
InsertProductInputSample.java

استرداد منتج تمت معالجته من حسابك

لاسترداد منتج تمت معالجته من حسابك، استخدِم الطريقة accounts.products.get. قد يستغرق ظهور المنتج الذي تمت معالجته بعد إدراجه عدة دقائق.

GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/products/{PRODUCT_NAME}

استبدِل {PRODUCT_NAME} باسم منتج مصدر الإدخال الذي تريد حذفه. مثلاً: online~en~US~sku123

يمكنك الحصول على اسم المورد للمنتج الذي تمت معالجته من حقل product في استجابة accounts.productInputs.insert.

لاسترداد منتج واحد لحساب معيّن على Merchant Center، يمكنك استخدام الطريقة google.shopping.merchant.accounts.v1beta.GetProductRequest ، كما هو موضّح في العيّنة التالية.

Java

  public static void getProduct(Config config, String product) throws Exception {

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

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

    // Calls the API and catches and prints any network failures/errors.
    try (ProductsServiceClient productsServiceClient =
        ProductsServiceClient.create(productsServiceSettings)) {

      // The name has the format: accounts/{account}/products/{productId}
      GetProductRequest request = GetProductRequest.newBuilder().setName(product).build();

      System.out.println("Sending get product request:");
      Product response = productsServiceClient.getProduct(request);

      System.out.println("Retrieved Product below");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println(e);
    }
  }
GetProductSample.java

حذف إدخال منتج من حسابك

لحذف إدخال منتج من حسابك، استخدِم الطريقة accounts.productInputs.delete. لحذف منتج باستخدام Merchant Products API، عليك إرسال المعرّف الفريد لمصدر البيانات الأساسي أو الإضافي الذي ينتمي إليه المنتج.

يوضّح الطلب التالي كيفية استخدام الإجراء accounts.productInputs.delete لحذف إدخال منتج:

DELETE https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/productInputs/{PRODUCT_NAME}?dataSource=accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}

استبدِل {PRODUCT_NAME} باسم مورد الإدخال المرتبط بالمنتج الذي تريد حذفه. مثلاً: online~en~US~sku123

لحذف منتج من حساب معيّن على Merchant Center، يمكنك استخدام الطريقة التالية: google.shopping.merchant.accounts.v1beta.DeleteProductInputRequest ، كما هو موضّح في العيّنة التالية.

Java

  public static void deleteProductInput(Config config, String productId, String dataSource)
      throws Exception {

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

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

    // Creates product name to identify product.
    String name =
        ProductInputName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setProductinput(productId)
            .build()
            .toString();

    // Calls the API and catches and prints any network failures/errors.
    try (ProductInputsServiceClient productInputsServiceClient =
        ProductInputsServiceClient.create(productInputsServiceSettings)) {
      DeleteProductInputRequest request =
          DeleteProductInputRequest.newBuilder().setName(name).setDataSource(dataSource).build();

      System.out.println("Sending deleteProductInput request");
      productInputsServiceClient.deleteProductInput(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. If you make a products.get or products.list request before a few"
              + " minutes have passed, the old product data may be returned.");
    } catch (Exception e) {
      System.out.println(e);
    }
  }
DeleteProductInputSample.java

إدراج المنتجات من حسابك

لإدراج المنتجات التي تمت معالجتها في حسابك، استخدِم accounts.products.list الطريقة، كما هو موضّح في الطلب التالي.

GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/products

لعرض منتج في حساب معيّن على Merchant Center، يمكنك استخدام الطريقة google.shopping.merchant.accounts.v1beta.ListProductsRequest ، كما هو موضّح في العيّنة التالية.

Java

  public static void listProducts(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.
    ProductsServiceSettings productsServiceSettings =
        ProductsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

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

    // Calls the API and catches and prints any network failures/errors.
    try (ProductsServiceClient productsServiceClient =
        ProductsServiceClient.create(productsServiceSettings)) {

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

      System.out.println("Sending list products request:");
      ListProductsPagedResponse response = productsServiceClient.listProducts(request);

      int count = 0;

      // 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 (Product product : response.iterateAll()) {

        System.out.println(product); // The product includes the `productStatus` field
        // That shows approval and disapproval information.

        count++;
      }
      System.out.print("The following count of products were returned: ");
      System.out.println(count);
    } catch (Exception e) {
      System.out.println("An error has occured: ");
      System.out.println(e);
    }
  }
ListProductsSample.java