نقل البيانات من واجهة برمجة التطبيقات SOAP في "مدير إعلانات Google"

‫Ad Manager SOAP API هي واجهة برمجة تطبيقات قديمة تُستخدَم لقراءة بيانات "مدير إعلانات Google" وكتابتها وإنشاء التقارير. إذا كان بإمكانك نقل البيانات، ننصحك باستخدام واجهة برمجة التطبيقات (API) الخاصة بـ "مدير إعلانات Google" (إصدار تجريبي). ومع ذلك، تتوافق إصدارات Ad Manager SOAP API مع دورة حياتها النموذجية. لمزيد من المعلومات، يُرجى الاطّلاع على جدول الإيقاف النهائي لواجهة برمجة التطبيقات SOAP في "مدير إعلانات Google".

يوضّح الدليل التالي الاختلافات بين واجهة برمجة التطبيقات المستندة إلى بروتوكول SOAP في "مدير إعلانات Google" وواجهة برمجة التطبيقات (الإصدار التجريبي) في "مدير إعلانات Google".

التعلُّم

تتضمّن طرق خدمة Ad Manager SOAP API العادية مفاهيم مكافئة في Ad Manager API. تتضمّن واجهة برمجة التطبيقات الخاصة بـ "مدير إعلانات Google" أيضًا طرقًا لقراءة كيانات فردية. يعرض الجدول التالي مثالاً على عملية الربط لطُرق Order:

طريقة SOAP طُرق REST
getOrdersByStatement networks.orders.get
networks.orders.list

مصادقة

لإجراء المصادقة باستخدام Ad Manager API (إصدار تجريبي)، يمكنك استخدام بيانات اعتماد Ad Manager SOAP API الحالية أو إنشاء بيانات اعتماد جديدة. في كلتا الحالتين، يجب أولاً تفعيل Ad Manager API في مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الاطّلاع على المصادقة.

إذا كنت تستخدم مكتبة برامج، عليك إعداد بيانات الاعتماد التلقائية للتطبيق من خلال ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف مفتاح حساب الخدمة. لمزيد من التفاصيل، يُرجى الاطّلاع على طريقة عمل "بيانات الاعتماد التلقائية للتطبيق".

إذا كنت تستخدم بيانات اعتماد تطبيق مثبَّت، أنشئ ملف JSON بالتنسيق التالي واضبط متغيّر البيئة على مساره بدلاً من ذلك:

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

استبدِل القيم التالية:

  • CLIENT_ID: معرّف العميل الجديد أو الحالي
  • CLIENT_SECRET: مفتاح سر العميل الجديد أو الحالي.

  • REFRESH_TOKEN: رمز التحديث الجديد أو الحالي.

‫Linux أو macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

فهم الاختلافات في الفلاتر

تتيح لغة طلب البحث في واجهة برمجة التطبيقات (الإصدار التجريبي) لـ "مدير إعلانات Google" جميع ميزات "لغة طلب البحث الخاصة بالناشرين" (PQL)، ولكن توجد اختلافات كبيرة في بنية الجملة.

يوضّح هذا المثال الخاص بعرض عناصر Order التغييرات الرئيسية، مثل إزالة متغيرات الربط وعوامل التشغيل الحساسة لحالة الأحرف واستبدال عبارتَي ORDER BY وLIMIT بحقول منفصلة:

Ad Manager SOAP API 

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

Ad Manager API (إصدار تجريبي)

تنسيق JSON

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

عنوان URL مُشفَّر

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

تتيح واجهة برمجة التطبيقات في "مدير إعلانات Google" (الإصدار التجريبي) جميع إمكانات لغة طلب البحث في Ad Manager، مع الاختلافات التالية في بنية الجملة عن واجهة برمجة التطبيقات المستندة إلى SOAP في "مدير إعلانات Google":

  • المشغّلان AND وOR حسّاسان لحالة الأحرف في الإصدار التجريبي من Ad Manager API. يتم التعامل مع and وor بالأحرف الصغيرة على أنّهما سلسلتا بحث حرفيتان مجردتان، وهي ميزة في Ad Manager API (إصدار تجريبي) للبحث في الحقول.

    استخدام عوامل التشغيل بأحرف كبيرة

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    يتم التعامل مع الأحرف الصغيرة كأحرف حرفية

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false

  • الحرف * هو حرف بدل لمطابقة السلاسل. لا تتيح واجهة برمجة التطبيقات Ad Manager API (إصدار تجريبي) استخدام عامل التشغيل like.

    لغة طلب البحث في Ad Manager SOAP API

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    واجهة برمجة التطبيقات في "مدير إعلانات Google" (إصدار تجريبي)

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • يجب أن تظهر أسماء الحقول على الجانب الأيمن من عامل المقارنة:

    فلتر صالح

    updateTime > "2024-01-01T00:00:00Z"

    فلتر غير صالح

    "2024-01-01T00:00:00Z" < updateTime

  • لا تتيح واجهة برمجة التطبيقات (الإصدار التجريبي) في "مدير إعلانات Google" استخدام متغيرات الربط. يجب أن تكون جميع القيم مضمّنة.

  • يجب وضع القيم الحرفية للسلاسل التي تحتوي على مسافات بين علامتَي اقتباس مزدوجتَين، على سبيل المثال، "Foo bar". لا يمكنك استخدام علامات اقتباس فردية لتضمين القيم الحرفية للسلاسل.

إزالة عبارات الترتيب حسب

تحديد ترتيب الترتيب اختياري في Ad Manager API (إصدار تجريبي). إذا أردت تحديد ترتيب فرز لمجموعة النتائج، عليك إزالة عبارة PQL ORDER BY وتعيين الحقل orderBy بدلاً من ذلك:

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

نقل البيانات من الإزاحات إلى رموز التمييز الخاصة بتقسيم الصفحات

تستخدم واجهة برمجة التطبيقات (إصدار تجريبي) في "إدارة إعلانات Google" رموز تقسيم على عدّة صفحات بدلاً من عبارات LIMIT وOFFSET للتنقّل بين مجموعات النتائج الكبيرة.

تستخدِم واجهة برمجة التطبيقات (إصدار تجريبي) في "مدير إعلانات Google" المَعلمة pageSize للتحكّم في حجم الصفحة. على عكس عبارة LIMIT في Ad Manager SOAP API، لن يؤدي حذف حجم الصفحة إلى عرض مجموعة النتائج بأكملها. بدلاً من ذلك، تستخدم طريقة القائمة حجم صفحة تلقائيًا يبلغ 50. يضبط المثال التالي pageSize وpageToken كمَعلمات عناوين URL:

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

على عكس واجهة برمجة التطبيقات SOAP في "إدارة إعلانات Google"، قد تعرض واجهة برمجة التطبيقات (إصدار تجريبي) في "إدارة إعلانات Google" عددًا أقل من النتائج مقارنةً بحجم الصفحة المطلوب حتى إذا كانت هناك صفحات إضافية. استخدِم الحقل nextPageToken لتحديد ما إذا كانت هناك نتائج إضافية.

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

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50

نقل التقارير

يمكن لواجهة برمجة التطبيقات SOAP قراءة التقارير وعرضها فقط في أداة "التقارير" المتوقّفة نهائيًا. في المقابل، يمكن لواجهة REST API قراءة التقارير التفاعلية وكتابتها وتشغيلها فقط.

تتضمّن أدوات إعداد التقارير وواجهات برمجة التطبيقات مساحة معرّفات مختلفة. لا يمكن استخدام معرّف SavedQuery في SOAP API في REST API.

إذا كنت تستخدم SavedQuery، يمكنك نقل التقرير إلى تقرير تفاعلي في واجهة المستخدِم وإنشاء عملية ربط بين مساحتَي المعرّفات. لمزيد من المعلومات حول نقل التقارير، يُرجى الاطّلاع على مقالة نقل التقارير إلى "التقارير التفاعلية".

التعرّف على الاختلافات بين واجهات برمجة التطبيقات

تختلف طريقة تعامل واجهة SOAP API وواجهة REST API مع تعريفات التقارير ونتائجها على النحو التالي:

  • أضافت واجهة برمجة التطبيقات SOAP تلقائيًا السمة ID إلى النتائج عندما طلب التقرير NAME فقط. في واجهة REST API، يجب إضافة السمة ID بشكل صريح إلى ReportDefinition لكي يتم تضمينها في النتائج.

  • لم تتضمّن واجهة برمجة التطبيقات SOAP أنواعًا صريحة للمقاييس. تحدّد واجهة REST API نوع بيانات، ويتم توثيقه في قيمة التعداد Dimension. يُرجى العِلم أنّ سمات ENUM هي تعدادات مفتوحة. يجب التعامل مع قيم التعداد الجديدة وغير المعروفة عند تحليل النتائج.

  • فصلت واجهة SOAP API بين Dimensions وDimensionAttributes. تحتوي واجهة REST API على تعداد Dimension موحّد يتضمّن كليهما.

  • لم تكن واجهة SOAP API تفرض حدًا أقصى لعدد السمات. تتضمّن التقارير التفاعلية حدًا أقصى يبلغ 10 سمات في كلٍّ من واجهة المستخدم وواجهة برمجة التطبيقات. يتم احتساب السمات التي يتم تقسيمها حسب مساحة المعرّف نفسها كسمة واحدة. على سبيل المثال، يشكّل تضمين ORDER_NAME وORDER_ID وORDER_START_DATE بُعدًا واحدًا فقط عند احتساب الحدّ الأقصى.