REST Resource: accounts.promotions

المرجع: عرض ترويجي

يمثّل عرضًا ترويجيًا. يمكنك الاطّلاع على المقالات التالية للحصول على مزيد من التفاصيل.

في ما يلي السمات المطلوبة لإدخال المعلومات في العروض الترويجية من أجل اجتياز عمليات التحقّق من صحة البيانات:

بعد إدخال العرض الترويجي وتعديله، قد يستغرق استرداد العرض الترويجي النهائي عدّة دقائق.

تمثيل JSON 
{
  "name": string,
  "promotionId": string,
  "contentLanguage": string,
  "targetCountry": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "dataSource": string,
  "attributes": {
    object (Attributes)
  },
  "customAttributes": [
    {
      object (CustomAttribute)
    }
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "versionNumber": string
}
الحقول
name

string

المعرّف اسم الترويج. التنسيق: accounts/{account}/promotions/{promotion}
promotionId

string

مطلوب. قدّم المستخدِم المعرّف الترويجي لتحديد العرض الترويجي بشكلٍ فريد. اتّبِع الحدّ الأدنى من المتطلبات لتجنّب رفض العروض الترويجية.
contentLanguage

string

مطلوب. الرمز المكوَّن من حرفَين وفق المعيار ISO 639-1 للغة العرض الترويجي

تتوفّر العروض الترويجية للغات محدّدة فقط.
targetCountry

string

مطلوب. البلد المستهدَف المستخدَم كجزء من المعرّف الفريد يتم تمثيلها على شكل رمز CLDR للمنطقة.

تتوفّر العروض الترويجية في بلدان محدّدة فقط، وهي البيانات المجانية وإعلانات Shopping الإعلانات للمنتجات داخل المتجر.
redemptionChannel[]

enum (RedemptionChannel)

مطلوب. قناة تحصيل القيمة للعرض الترويجي يجب توفّر قناة واحدة على الأقل.
dataSource

string

النتائج فقط. مصدر البيانات الأساسي للعرض الترويجي.
attributes

object (Attributes)

اختياريّ. قائمة بسمات العرض الترويجي
customAttributes[]

object (CustomAttribute)

اختياريّ. قائمة بالسمات المخصّصة (التي يقدّمها التاجر) ويمكن أيضًا استخدامه لإرسال أيّ سمة من مواصفات البيانات بتنسيقها العام (على سبيل المثال، { "name": "size type", "value": "regular" }). ويُعدّ ذلك مفيدًا لإرسال السمات التي لا تعرضها واجهة برمجة التطبيقات بشكل صريح.
promotionStatus

object (PromotionStatus)

النتائج فقط. حالة العرض الترويجي، ومشاكل التحقّق من البيانات، أي معلومات عن عرض ترويجي يتم احتسابه بشكل غير متزامن
versionNumber

string (int64 format)

اختياريّ. يمثّل الإصدار الحالي (الحداثة) من العرض الترويجي، والذي يمكن استخدامه للحفاظ على الترتيب الصحيح عند إجراء عدّة تعديلات في الوقت نفسه.

في حال ضبطها، يتم منع الإدراج عندما يكون رقم الإصدار أقل من رقم الإصدار الحالي للعرض الترويجي الحالي. يمكن إجراء إعادة الإدراج (على سبيل المثال، إعادة عرض العرض الترويجي بعد 30 يومًا) باستخدام versionNumber الحالية.

في حال منع العملية، سيتم طرح استثناء تم إلغاؤه.

RedemptionChannel

قناة عرض عرض ترويجي

عمليات التعداد
REDEMPTION_CHANNEL_UNSPECIFIED يشير إلى أنّ القناة غير محدّدة.
IN_STORE يشير إلى أنّ القناة متوفّرة في المتجر. هذا مماثل لقناة local المستخدمة في products.
ONLINE يشير إلى أنّ القناة متصلة بالإنترنت.

السمات

السمات

تمثيل JSON 
{
  "productApplicability": enum (ProductApplicability),
  "offerType": enum (OfferType),
  "genericRedemptionCode": string,
  "longTitle": string,
  "couponValueType": enum (CouponValueType),
  "promotionDestinations": [
    enum (DestinationEnum)
  ],
  "itemIdInclusion": [
    string
  ],
  "brandInclusion": [
    string
  ],
  "itemGroupIdInclusion": [
    string
  ],
  "productTypeInclusion": [
    string
  ],
  "itemIdExclusion": [
    string
  ],
  "brandExclusion": [
    string
  ],
  "itemGroupIdExclusion": [
    string
  ],
  "productTypeExclusion": [
    string
  ],
  "minimumPurchaseAmount": {
    object (Price)
  },
  "minimumPurchaseQuantity": string,
  "limitQuantity": string,
  "limitValue": {
    object (Price)
  },
  "percentOff": string,
  "moneyOffAmount": {
    object (Price)
  },
  "getThisQuantityDiscounted": string,
  "freeGiftValue": {
    object (Price)
  },
  "freeGiftDescription": string,
  "freeGiftItemId": string,
  "promotionEffectiveTimePeriod": {
    object (Interval)
  },
  "promotionDisplayTimePeriod": {
    object (Interval)
  },
  "storeApplicability": enum (StoreApplicability),
  "storeCodesInclusion": [
    string
  ],
  "storeCodesExclusion": [
    string
  ],
  "promotionUrl": string
}
الحقول
productApplicability

enum (ProductApplicability)

مطلوب. يشير ذلك إلى ما إذا كان العرض الترويجي ينطبق على جميع المنتجات أو على منتجات معيّنة فقط.
offerType

enum (OfferType)

مطلوب. نوع العرض الترويجي استخدِم هذه السمة للإشارة إلى ما إذا كان العملاء بحاجة إلى رمز قسيمة لتحصيل قيمة العرض الترويجي.
genericRedemptionCode

string

اختياريّ. رمز تحصيل قيمة العرض الترويجي عام. أن تكون قابلة للاستخدام مع الحقل offerType وأن تستوفي الحد الأدنى من المتطلبات
longTitle

string

مطلوب. العنوان الكامل للعرض الترويجي
couponValueType

enum (CouponValueType)

مطلوب. سمة نوع قيمة القسيمة للإشارة إلى نوع العرض الترويجي الذي تقدّمه استنادًا إلى نوع قيمة القسيمة المحدّدة، تكون بعض السمات مطلوبة.
promotionDestinations[]

enum (DestinationEnum)

مطلوب. قائمة الوجهات التي ينطبق عليها العرض الترويجي إذا لم تحدّد وجهة من خلال إدراج قيمة مسموح بها في مصدر بياناتك، سيظهر العرض الترويجي الخاص بك في إعلانات Shopping وفي البيانات المجانية بشكل تلقائي.

من المحتمل أنّك أرسلت في السابق القيم التالية كوجهات لمنتجاتك: Shopping Actions وSurfaces across Google وLocal surfaces across Google. لتمثيل هذه القيم، استخدِم FREE_LISTINGS وFREE_LOCAL_LISTINGS وLOCAL_INVENTORY_ADS. لمزيد من التفاصيل، يُرجى الاطّلاع على وجهة العرض الترويجي.
itemIdInclusion[]

string

اختياريّ. فلترة المنتجات حسب معرّف السلعة للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على specific_products.
brandInclusion[]

string

اختياريّ. فلترة المنتجات حسب العلامة التجارية للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
itemGroupIdInclusion[]

string

اختياريّ. فلترة المنتجات حسب معرّف مجموعة السلع للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي [productApplicability] على القيمة specific_products.
productTypeInclusion[]

string

اختياريّ. فلتر المنتجات حسب نوع المنتج للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
itemIdExclusion[]

string

اختياريّ. فلترة المنتجات حسب استبعاد معرّف السلعة في العرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
brandExclusion[]

string

اختياريّ. فلترة المنتجات حسب استبعاد العلامة التجارية للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على specific_products.
itemGroupIdExclusion[]

string

اختياريّ. فلترة المنتجات حسب معرّف مجموعة السلع لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products. استبعاد للعرض الترويجي.
productTypeExclusion[]

string

اختياريّ. فلتر المنتجات حسب استبعاد نوع المنتج للعرض الترويجي لا تنطبق سمات فلاتر المنتجات إلا عند ضبط سمة المنتجات المؤهلة ليسري عليها العرض الترويجي productApplicability على القيمة specific_products.
minimumPurchaseAmount

object (Price)

اختياريّ. الحدّ الأدنى لمبلغ الشراء للاستفادة من العرض الترويجي
minimumPurchaseQuantity

string (int64 format)

اختياريّ. الحدّ الأدنى لكمية السلع المطلوب شراؤها للاستفادة من العرض الترويجي
limitQuantity

string (int64 format)

اختياريّ. الحدّ الأقصى المسموح به لكمية السلع الممكن شراؤها من العرض الترويجي.
limitValue

object (Price)

اختياريّ. الحدّ الأقصى لسعر المنتج في العرض الترويجي
percentOff

string (int64 format)

اختياريّ. النسبة المئوية للخصم المقدَّمة في العرض الترويجي
moneyOffAmount

object (Price)

اختياريّ. المبلغ المخفَّض المقدَّم في العرض الترويجي
getThisQuantityDiscounted

string (int64 format)

اختياريّ. عدد السلع التي تُباع بخصم في العرض الترويجي يتم ضبط السمة عندما تكون قيمة couponValueType تساوي buy_m_get_n_money_off أو buy_m_get_n_percent_off.
freeGiftValue

object (Price)

اختياريّ. قيمة الهدية المجانية للعرض الترويجي
freeGiftDescription

string

اختياريّ. وصف الهدية المجانية للعرض الترويجي
freeGiftItemId

string

اختياريّ. معرّف السلعة الخاصة بالهدية المجانية للعرض الترويجي
promotionEffectiveTimePeriod

object (Interval)

مطلوب. تمثيل TimePeriod لتواريخ سريان العرض الترويجي تحدّد هذه السمة أنّه يمكن اختبار العرض الترويجي في متجرك على الإنترنت خلال هذه الفترة الزمنية.
promotionDisplayTimePeriod

object (Interval)

اختياريّ. TimePeriod تمثيل تواريخ عرض العرض الترويجي تحدّد هذه السمة التاريخ والإطار الزمني لنشر العرض الترويجي على Google.com وإعلانات Shopping. إذا لم يتم تحديد سمة الفترة الزمنية لعرض العرض الترويجي promotionDisplayTimePeriod، ستحدّد سمة الفترة الزمنية لسريان العرض الترويجي promotionEffectiveTimePeriod كلاً من التاريخ والإطار الزمني لعرض الإعلان الترويجي على Google.com وإعلانات Shopping.
storeApplicability

enum (StoreApplicability)

اختياريّ. ما إذا كان العرض الترويجي ينطبق على جميع المتاجر أو متاجر محدّدة فقط تؤدي العروض الترويجية لإعلانات المنتجات داخل المتجر إلى ظهور خطأ في حال عدم تضمين مدى توفّر المنتج في المتجر. يتم طرح خطأ INVALID_ARGUMENT إذا تم ضبط storeApplicability على ALL_STORES وتم ضبط storeCodesInclusion أو score_code_exclusion على قيمة.
storeCodesInclusion[]

string

اختياريّ. رموز المتاجر المطلوب تضمينها في العرض الترويجي لا تنطبق سمات فلاتر المتاجر إلا عند ضبط سمة storeApplicability على specific_stores.

رمز المتجر (رقم تعريف المتجر من ملفك التجاري) للمتجر الذي يتم بيع المنتج فيه اطّلِع على مواصفات بيانات المنتجات المتوفّرة داخل المتجر للحصول على مزيد من المعلومات.
storeCodesExclusion[]

string

اختياريّ. رموز المتاجر المطلوب استبعادها للعرض الترويجي لا تنطبق سمات فلاتر المتاجر إلا عند ضبط سمة storeApplicability على specific_stores.
promotionUrl

string

اختياريّ. تمثّل هذه السمة عنوان URL يؤدي إلى الصفحة على موقع التاجر الإلكتروني حيث يظهر العرض الترويجي. تؤدي العروض الترويجية لإعلانات المنتجات داخل المتجر إلى ظهور خطأ في حال عدم تضمين promotionUrl. يتم استخدام عنوان URL للتأكّد من صلاحية العرض الترويجي وإمكانية تحصيل قيمته.

ProductApplicability

المنتج أو قائمة المنتجات التي ينطبق عليها العرض الترويجي

عمليات التعداد
PRODUCT_APPLICABILITY_UNSPECIFIED لا نعرف المنتجات التي ينطبق عليها العرض الترويجي.
ALL_PRODUCTS تنطبق على جميع المنتجات.
SPECIFIC_PRODUCTS ينطبق على منتج واحد أو قائمة منتجات فقط.

OfferType

نوع العرض الترويجي

عمليات التعداد
OFFER_TYPE_UNSPECIFIED نوع العرض الترويجي غير معروف.
NO_CODE نوع العرض بدون رمز
GENERIC_CODE نوع العرض الترويجي مع رمز يجب إدخال رمز عام لتحصيل قيمة العرض الترويجي عندما يكون offerType = GENERIC_CODE.

CouponValueType

نوع قيمة القسيمة لعرض ترويجي.

عمليات التعداد
COUPON_VALUE_TYPE_UNSPECIFIED يشير هذا الرمز إلى أنّ نوع قيمة القسيمة غير محدّد.
MONEY_OFF نوع قيمة القسيمة التي تقدّم خصمًا نقديًا
PERCENT_OFF نوع قيمة القسيمة التي تقدّم خصمًا بنسبة مئوية.
BUY_M_GET_N_MONEY_OFF شراء كمية M والحصول على خصم بقيمة N من نوع قيمة القسيمة يجب أن يكون minimumPurchaseQuantity وgetThisQuantityDiscounted متوفّرَين. يجب أيضًا أن يكون moneyOffAmount متوفّرًا.
BUY_M_GET_N_PERCENT_OFF شراء كمية M والحصول على خصم بنسبة N من نوع قيمة القسيمة يجب أن يكون minimumPurchaseQuantity وgetThisQuantityDiscounted متوفّرَين. يجب أن يكون الحقل "percent_off_percentage" متوفرًا أيضًا.
BUY_M_GET_MONEY_OFF خصم على السعر عند شراء كمية M. يجب أن يكون الحقلان minimumPurchaseQuantity وmoneyOffAmount متوفّرَين.
BUY_M_GET_PERCENT_OFF خصم على السعر عند شراء كمية M. يجب أن يكون الحقلان minimumPurchaseQuantity وpercent_off_percentage متوفّرَين.
FREE_GIFT هدية مجانية مع الوصف فقط
FREE_GIFT_WITH_VALUE هدية مجانية ذات قيمة مالية
FREE_GIFT_WITH_ITEM_ID هدية مجانية مع معرّف السلعة
FREE_SHIPPING_STANDARD نوع قيمة قسيمة الشحن العادي المجاني
FREE_SHIPPING_OVERNIGHT نوع قيمة قسيمة الشحن المجاني في اليوم التالي
FREE_SHIPPING_TWO_DAY نوع قيمة قسيمة الشحن المجاني في غضون يومَين

DestinationEnum

قيم الوجهة

عمليات التعداد
DESTINATION_ENUM_UNSPECIFIED لم يتم تحديده.
SHOPPING_ADS إعلانات Shopping:
DISPLAY_ADS الإعلانات الصورية:
LOCAL_INVENTORY_ADS إعلانات المستودعات الفعليّة المحليّة.
FREE_LISTINGS البيانات المجانية:
FREE_LOCAL_LISTINGS بيانات المنتج المحلية المجانية:
YOUTUBE_SHOPPING التسوّق على YouTube
YOUTUBE_SHOPPING_CHECKOUT الدفع على YouTube Shopping
YOUTUBE_AFFILIATE الشركاء التابعون في YouTube
FREE_VEHICLE_LISTINGS بيانات المركبات المجانية
VEHICLE_ADS إعلانات المركبات
CLOUD_RETAIL البيع بالتجزئة على السحابة الإلكترونية
LOCAL_CLOUD_RETAIL البيع بالتجزئة على السحابة الإلكترونية المحلية

StoreApplicability

رموز المتاجر أو قائمة برموز المتاجر التي ينطبق عليها العرض الترويجي للعروض الترويجية لإعلانات المنتجات داخل المتجر فقط

عمليات التعداد
STORE_APPLICABILITY_UNSPECIFIED رموز المتاجر التي ينطبق عليها العرض الترويجي غير معروفة.
ALL_STORES ينطبق العرض الترويجي على جميع المتاجر.
SPECIFIC_STORES ينطبق العرض الترويجي على المتاجر المحدّدة فقط.

PromotionStatus

حالة العرض الترويجي

تمثيل JSON 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
الحقول
destinationStatuses[]

object (DestinationStatus)

النتائج فقط. الوجهات المقصودة للعرض الترويجي
itemLevelIssues[]

object (ItemLevelIssue)

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

string (Timestamp format)

النتائج فقط. تاريخ إنشاء العرض الترويجي بتنسيق ISO 8601: التاريخ والوقت والمعادلة، على سبيل المثال 2020-01-02T09:00:00+01:00 أو 2020-01-02T09:00:00Z
lastUpdateDate

string (Timestamp format)

النتائج فقط. تاريخ آخر تعديل لحالة العرض الترويجي بتنسيق ISO 8601: التاريخ والوقت والمعادلة، على سبيل المثال 2020-01-02T09:00:00+01:00 أو 2020-01-02T09:00:00Z

DestinationStatus

حالة الوجهة المحددة.

تمثيل JSON 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
الحقول
reportingContext

enum (ReportingContextEnum)

النتائج فقط. اسم وجهة العرض الترويجي.
status

enum (State)

النتائج فقط. حالة الوجهة المحددة.

الحالة

الحالة الحالية للعرض الترويجي

عمليات التعداد
STATE_UNSPECIFIED حالة الترويج غير معروفة.
IN_REVIEW إنّ العرض الترويجي قيد المراجعة.
REJECTED تم رفض العرض الترويجي.
LIVE تمّت الموافقة على العرض الترويجي وهو نشط.
STOPPED أوقف التاجر العرض الترويجي.
EXPIRED لم يعُد العرض الترويجي نشطًا.
PENDING لا يتم إيقاف العرض الترويجي، وتمت الموافقة على جميع المراجعات، ولكن سيكون تاريخ تفعيلها في المستقبل.

ItemLevelIssue

المشكلة المرتبطة بالعرض الترويجي

تمثيل JSON 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
الحقول
code

string

النتائج فقط. رمز الخطأ للمشكلة.
severity

enum (Severity)

النتائج فقط. كيفية تأثير هذه المشكلة في عرض العرض الترويجي
resolution

string

النتائج فقط. ما إذا كان بإمكان التاجر حلّ المشكلة
attribute

string

النتائج فقط. اسم السمة، إذا كانت المشكلة ناتجة عن سمة واحدة
reportingContext

enum (ReportingContextEnum)

النتائج فقط. الوجهة التي تنطبق عليها المشكلة
description

string

النتائج فقط. وصف موجز للمشكلة باللغة الإنجليزية
detail

string

النتائج فقط. وصف تفصيلي للمشكلة باللغة الإنجليزية
documentation

string

النتائج فقط. عنوان URL لصفحة ويب للمساعدة في حلّ هذه المشكلة
applicableCountries[]

string

النتائج فقط. قائمة برموز البلدان (ISO 3166-1 alpha-2) التي تنطبق فيها المشكلة على العرض.

درجة الخطورة

درجة خطورة المشكلة

عمليات التعداد
SEVERITY_UNSPECIFIED غير محدّد
NOT_IMPACTED هذه المشكلة هي تحذير ولا تؤثّر بشكل مباشر في العرض الترويجي.
DEMOTED تمّت ترقية العرض الترويجي ومن المرجّح أن يحقّق أداءً محدودًا في نتائج البحث
DISAPPROVED تؤدي المشكلة إلى رفض العرض الترويجي.

الطُرق

get

 لاسترداد العرض الترويجي من حسابك على Merchant Center.

insert

 تُدرج عرضًا ترويجيًا لحسابك على Merchant Center.

list

 يعرض هذا القسم العروض الترويجية في حسابك على Merchant Center.