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 و"منصات Google" و"منصات 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 listings (البيانات المجانية):
FREE_LOCAL_LISTINGS بيانات المنتج المحلية المجانية:
YOUTUBE_SHOPPING التسوّق على YouTube:

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.