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

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

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

التعلُّم

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

طريقة 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، مع اختلافات نحوية التالية عن واجهة برمجة التطبيقات SOAP API في "مدير إعلانات Google":

  • عاملا التشغيل AND وOR حساسان لحالة الأحرف في Ad Manager API (الإصدار التجريبي). يتم التعامل مع and وor بالتنسيق الصغير كسلسلتَي بحث LITERAL فارغتَين، وهي ميزة في 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) في واجهة SOAP API لخدمة "مدير إعلانات Google"

    // 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}

على عكس واجهة SOAP API في "مدير إعلانات 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