از Ad Manager SOAP API مهاجرت کنید

Ad Manager SOAP API یک API قدیمی برای خواندن و نوشتن داده‌های Ad Manager و اجرای گزارش‌ها است. اگر می‌توانید مهاجرت کنید، توصیه می‌کنیم از Ad Manager API (بتا) استفاده کنید. با این حال، نسخه‌های Ad Manager SOAP API برای چرخه عمر معمولی خود پشتیبانی می‌شوند. برای اطلاعات بیشتر، Ad Manager SOAP API Deprecation Schedule را ببینید.

راهنمای زیر تفاوت‌های بین 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 : رمز به‌روزرسانی جدید یا موجود شما.

لینوکس یا macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

ویندوز 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

تفاوت فیلترها را درک کنید

زبان جستجوی Ad Manager API (بتا) از همه ویژگی‌های زبان پرس و جو ناشر (PQL) پشتیبانی می‌کند، اما تفاوت‌های نحوی قابل توجهی وجود دارد.

این مثال برای فهرست کردن اشیاء Order تغییرات عمده مانند حذف متغیرهای bind، عملگرهای حساس به حروف کوچک و بزرگ و جایگزینی بندهای 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 پشتیبانی نمی کند.

    Ad Manager SOAP API PQL

    // 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 (بتا) از متغیرهای bind پشتیبانی نمی کند. همه مقادیر باید خطی شوند.

  • حروف رشته‌ای حاوی فاصله باید در گیومه‌های دوتایی پیچیده شوند، به عنوان مثال، "Foo bar" . شما نمی توانید از نقل قول های تک برای بسته بندی حرف های رشته ای استفاده کنید.

حذف ترتیب توسط بندها

تعیین ترتیب مرتب سازی در Ad Manager API (بتا) اختیاری است. اگر می‌خواهید ترتیب مرتب‌سازی را برای مجموعه نتایج خود مشخص کنید، عبارت PQL ORDER BY را حذف کنید و به جای آن قسمت 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