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

رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (Ad Manager SOAP 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

احراز هویت

برای احراز هویت با رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (بتا)، می‌توانید از اعتبارنامه‌های API SOAP مدیریت تبلیغات موجود خود استفاده کنید یا اعتبارنامه‌های جدیدی ایجاد کنید. در هر دو صورت، ابتدا باید رابط برنامه‌نویسی کاربردی مدیریت تبلیغات را در پروژه 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 (بتا) از تمام ویژگی‌های Publisher Query Language (PQL) پشتیبانی می‌کند، اما تفاوت‌های نحوی قابل توجهی وجود دارد.

این مثال برای فهرست کردن اشیاء Order ، تغییرات عمده‌ای مانند حذف متغیرهای bind، عملگرهای حساس به حروف بزرگ و کوچک و جایگزینی عبارات ORDER BY و LIMIT با فیلدهای جداگانه را نشان می‌دهد:

رابط برنامه‌نویسی کاربردی SOAP مدیر تبلیغات

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

رابط برنامه‌نویسی کاربردی مدیر تبلیغات (بتا)

فرمت 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\"

رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (بتا) از تمام قابلیت‌های PQL پشتیبانی می‌کند، با این تفاوت‌های نحوی زیر نسبت به رابط برنامه‌نویسی کاربردی SOAP مدیریت تبلیغات:

• عملگرهای AND و OR در رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (بتا) به حروف کوچک و بزرگ حساس هستند. حروف کوچک and و or به عنوان رشته‌های جستجوی تحت‌اللفظی ساده در نظر گرفته می‌شوند، که این ویژگی در رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (بتا) برای جستجو در بین فیلدها وجود دارد.

  از عملگرهای حروف بزرگ استفاده کنید

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

• کاراکتر * یک علامت اختصاری برای تطبیق رشته است. رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (بتا) از عملگر like پشتیبانی نمی‌کند.

  مدیریت تبلیغات SOAP API PQL

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

  رابط برنامه‌نویسی کاربردی مدیر تبلیغات (بتا)

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

• نام فیلدها باید در سمت چپ عملگر مقایسه‌ای ظاهر شود:

  فیلتر معتبر

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

  فیلتر نامعتبر

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

• رابط برنامه‌نویسی کاربردی مدیر تبلیغات (بتا) از متغیرهای اتصال پشتیبانی نمی‌کند. همه مقادیر باید درون‌خطی باشند.

• رشته‌های دارای فاصله (Literal) باید داخل علامت نقل قول دوتایی (Double Quotes) قرار بگیرند، برای مثال، "Foo bar" . شما نمی‌توانید از علامت نقل قول تکی برای قرار دادن رشته‌های دارای فاصله (Literal) استفاده کنید.

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

تعیین ترتیب مرتب‌سازی در رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (بتا) اختیاری است. اگر می‌خواهید برای مجموعه نتایج خود ترتیب مرتب‌سازی تعیین کنید، عبارت PQL ORDER BY را حذف کرده و به جای آن فیلد orderBy را تنظیم کنید:

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

نکته: در حالی که API SOAP مدیر تبلیغات (Ad Manager) توصیه می‌کند که همیشه یک بند ORDER BY برای اطمینان از ثبات صفحه‌بندی لحاظ شود، API مدیر تبلیغات (بتا) ثبات را با توکن‌های صفحه‌بندی حفظ می‌کند.

مهاجرت از offsetها به توکن‌های صفحه‌بندی

رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (بتا) برای صفحه‌بندی در مجموعه‌های بزرگ نتایج، به جای عبارات LIMIT و OFFSET از توکن‌های صفحه‌بندی استفاده می‌کند.

رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (نسخه بتا) از پارامتر pageSize برای کنترل اندازه صفحه استفاده می‌کند. برخلاف عبارت LIMIT در رابط برنامه‌نویسی کاربردی مدیریت تبلیغات SOAP، حذف اندازه صفحه، کل مجموعه نتایج را برنمی‌گرداند . در عوض، متد list از اندازه پیش‌فرض صفحه 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

گزارش‌ها را منتقل کنید

API مربوط به SOAP فقط می‌تواند گزارش‌ها را در ابزار منسوخ‌شده‌ی Reports بخواند و اجرا کند. برعکس، API مربوط به REST فقط می‌تواند گزارش‌های تعاملی را بخواند، بنویسد و اجرا کند.

ابزارهای گزارش‌گیری و APIها فضای شناسه متفاوتی دارند. شناسه یک SavedQuery در SOAP API را نمی‌توان در REST API استفاده کرد.

اگر از SavedQuery استفاده می‌کنید، می‌توانید گزارش را در رابط کاربری به یک گزارش تعاملی منتقل کنید و بین دو فضای شناسه، نگاشتی ایجاد کنید. برای اطلاعات بیشتر در مورد مهاجرت گزارش‌ها، به Migrate reports to Interactive reports مراجعه کنید.

تفاوت‌های API را درک کنید

تفاوت‌هایی در نحوه‌ی مدیریت تعاریف و نتایج گزارش توسط SOAP API و REST API وجود دارد:

• API مربوط به SOAP به طور خودکار یک بُعد ID مربوطه را به نتایج اضافه می‌کرد، زمانی که یک گزارش فقط NAME درخواست می‌کرد. در REST API، شما باید بُعد ID را به طور صریح به ReportDefinition اضافه کنید تا در نتایج گنجانده شود.

• API SOAP انواع صریحی برای معیارها نداشت. API REST یک نوع داده تعریف می‌کند که در مورد مقدار شمارشی Dimension مستند شده است. توجه داشته باشید که ابعاد ENUM شمارش‌های باز هستند. هنگام تجزیه نتایج، باید مقادیر شمارشی جدید و ناشناخته را مدیریت کنید.

• API SOAP Dimensions و DimensionAttributes را از هم جدا می‌کرد. API REST یک Dimension enum یکپارچه دارد که شامل هر دو است.

• API مربوط به SOAP محدودیتی در تعداد ابعاد نداشت. گزارش‌های تعاملی هم در رابط کاربری و هم در API محدودیت ۱۰ بُعد دارند. ابعادی که با فضای شناسه یکسان تجزیه می‌شوند، به عنوان یک بُعد واحد شمارش می‌شوند. برای مثال، شامل ORDER_NAME ، ORDER_ID و ORDER_START_DATE هنگام محاسبه محدودیت، فقط به عنوان ۱ بُعد شمارش می‌شوند.