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

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

يحدّد الدليل التالي الاختلافات بين Ad Manager SOAP API وAd Manager API (الإصدار التجريبي).

التعلُّم

تتضمّن طرق خدمة Ad Manager SOAP API العادية مفاهيم مكافئة في Ad Manager API. تتضمّن Ad Manager API أيضًا طرقًا لقراءة الكيانات الفردية. يوضّح الجدول التالي مثالاً على ربط طرق 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

التعرّف على الاختلافات في الفلاتر

تتيح لغة طلبات البحث في Ad Manager API (الإصدار التجريبي) جميع ميزات لغة طلبات الناشرين (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\"

تتيح Ad Manager API (الإصدار التجريبي) جميع إمكانات لغة طلبات الناشرين (PQL)، مع الاختلافات التالية في البنية عن Ad Manager SOAP API:

  • عاملَا التشغيل 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.

    لغة طلبات الناشرين (PQL) في Ad Manager SOAP API

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

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

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

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

    فلتر صالح

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

    فلتر غير صالح

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

  • لا تتيح Ad Manager API (الإصدار التجريبي) متغيّرات الربط. يجب تضمين جميع القيم.

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

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

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

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

نقل البيانات من الإزاحات إلى رموز تقسيم النتائج على عدّة صفحات

تستخدم Ad Manager API (الإصدار التجريبي) رموز تقسيم النتائج على عدّة صفحات بدلاً من عبارتَي LIMIT وOFFSET لتقسيم مجموعات النتائج الكبيرة على عدّة صفحات.

تستخدم Ad Manager API (الإصدار التجريبي) المَعلمة 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}

على عكس Ad Manager SOAP API، قد تعرض Ad Manager API (الإصدار التجريبي) عددًا أقل من النتائج من حجم الصفحة المطلوب حتى إذا كانت هناك صفحات إضافية. استخدِم الحقل 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 API سوى قراءة التقارير وعرضها في أداة "التقارير" التي تم إيقافها نهائيًا. في المقابل، لا يمكن لواجهة REST API سوى قراءة "التقارير التفاعلية" وكتابتها وعرضها.

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

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

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

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

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

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

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

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