التوافق مع Content API for Shopping

يمكنك استخدام هذا الدليل لدمج Merchant API مع عملية تنفيذ Content API for Shopping الحالية.

البدء

اطّلِع على تصميم Merchant API لمعرفة تفاصيل حول Merchant API وواجهات برمجة التطبيقات الفرعية.

لبدء استخدام Merchant API، غيِّر عناوين URL للطلبات إلى التنسيق التالي:

https://merchantapi.googleapis.com/{sub-API}/{version}/{resource name}:{method}…

اطّلِع على دليل البدء السريع ومرجع Merchant API للحصول على مزيد من المعلومات.

توفُّر واجهة برمجة التطبيقات gRPC

تتوافق Merchant API مع gRPC وREST. يمكنك استخدام برمجة التطبيقات برمجة التطبيقات لواجهة برمجة التطبيقات Merchant API وREST لواجهة برمجة التطبيقات Content API for Shopping في الوقت نفسه.

تتطلّب مكتبات عملاء Merchant API استخدام مكتبة برمجة التطبيقات gRPC.

راجِع مقالة استخدام gRPC للحصول على مزيد من المعلومات.

التوافق

يصف هذا الدليل التغييرات العامة التي تنطبق على Merchant API بالكامل. اطّلِع على الأدلّة التالية لمعرفة التغييرات التي طرأت على ميزات معيّنة:

• نقل إدارة الحسابات
• نقل إعدادات الشحن
• إدارة نقل بيانات المنتجات
• نقل إدارة مصادر البيانات
• نقل إدارة المستودعات الإعلانية
• نقل إدارة العروض الترويجية
• نقل إدارة إعداد التقارير
• نقل إدارة مصادر الإحالات الناجحة
• نقل إدارة الشراكة في الخلاصات المحلية

تم تصميم Merchant API للعمل مع ميزات الإصدار 2.1 الحالي من Content API في Shopping.

على سبيل المثال، يمكنك استخدام Merchant Inventories API مع عملية التنفيذ الحالية لإصدار 2.1 من Content API for Shopping products. يمكنك استخدام Content API for Shopping لتحميل منتج جديد داخل المتجر (الذي تبيعه في متجر محلي)، ثم استخدام Merchant Inventories API LocalInventory لإدارة المعلومات داخل المتجر لهذا المنتج.

ملاحظة: لا يمكننا ضمان التوافق الكامل مع الإصدارات السابقة للميزات المشابهة بين Content API for Shopping وMerchant API بسبب التصميم المحسّن. على سبيل المثال، قد تختلف أسماء الحقول أو مدى توفّر الطريقة في المرجع نفسه في Content API for Shopping وMerchant API.

طلبات مجمّعة

لا تتيح واجهة برمجة التطبيقات Merchant API استخدام طريقة customBatch المعروضة في Content API for Shopping. بدلاً من ذلك، يمكنك الاطّلاع على إرسال طلبات متعددة في آنٍ واحد أو تنفيذ طلباتك بشكل غير متزامن.

يوضّح المثال التالي كيفية إدراج إدخال منتج.

Java

  public static void asyncInsertProductInput(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)) {

      // Creates five insert product input requests with random product IDs.
      List<InsertProductInputRequest> requests = new ArrayList<>(5);
      for (int i = 0; i < 5; i++) {
        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(createRandomProduct())
                .build();

        requests.add(request);
      }

      System.out.println("Sending insert product input requests");
      List<ApiFuture<ProductInput>> futures =
          requests.stream()
              .map(
                  request ->
                      productInputsServiceClient.insertProductInputCallable().futureCall(request))
              .collect(Collectors.toList());

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

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

    } catch (Exception e) {
      System.out.println(e);
    }
  }
InsertProductInputAsyncSample.java

إذا كنت تستخدِم customBatch في Content API وتحتاج إلى هذه الميزة في Merchant API، يُرجى إخبارنا بالسبب في ملاحظاتك.

المعرفات

بما يتوافق مع مبادئ تحسين واجهات برمجة التطبيقات في Google، أجرينا بعض التغييرات على المعرّفات لموارد Merchant API.

الاسم يحلّ محلّ المعرّف

تستخدم جميع موارد Merchant API حقل name كمعرّف فريد لها.

في ما يلي مثال على كيفية استخدام حقل name في مكالماتك:

POST https://merchantapi.googleapis.com/inventories/v1beta/{parent}/regionalInventories:insert

يتم عرض حقل name الجديد هذا كمعرّف المورد لجميع طلبات القراءة والكتابة في Merchant API.

ملاحظة مهمة: ننصحك باستخدام القيمة من حقل name مباشرةً في طلباتك، بدلاً من تحليل اسم المورد أو إنشائه يدويًا لتجنُّب المشاكل.

على سبيل المثال، يمكنك تنفيذ طريقة getName() لاسترداد name من مورد، وتخزين الإخراج كمتغيّر بدلاً من إنشاء name من معرّفات التاجر والمورد بنفسك.

حقول العناصر الرئيسية لموارد العناصر الفرعية

في Merchant API، تحتوي جميع الموارد الفرعية على الحقل parent. يمكنك استخدام حقل parent لتحديد name المورد الذي تريد إدراج المورد الفرعي فيه، بدلاً من تمرير المورد الرئيسي بالكامل. يمكنك أيضًا استخدام الحقل parent مع طرق list لعرض الموارد الفرعية لهذا parent.

على سبيل المثال، لعرض مستودعات المنتجات داخل المتجر لمنتج معيّن، حدِّد name المنتج في الحقل parent لطريقة list. في هذه الحالة، يكون product المحدَّد هو parent من موارد LocalInventory المعروضة.

الأنواع

في ما يلي بعض الأنواع الشائعة التي تتم مشاركتها في واجهات برمجة التطبيقات الفرعية لواجهة Merchant API.

السعر

في ما يلي التغييرات التي طرأت على Price في حزمة Merchant Common:

	Content API	Merchant API
حقل المبلغ	value:string	amountMicros:int64
حقل العملة	currency:string	currencyCode:string

يتم الآن تسجيل مبلغ Price بالوحدات الميكرو، حيث يساوي مليون وحدة ميكرو وحدة عملتك العادية.

في Content API for Shopping، كان Price رقمًا عشريًا في شكل سلسلة.

تم تغيير اسم حقل المبلغ من value إلى amountMicros

تم تغيير اسم حقل العملة من currency إلى currencyCode. يظل التنسيق هو ISO 4217.