سرصفحه‌های درخواست و پاسخ SOAP XML

این صفحه اطلاعاتی درباره سرایندهای درخواست SOAP XML موردنیاز و سرایندهایی که در پاسخ برگردانده می‌شوند ارائه می‌دهد.

سرصفحه‌های درخواست الزامی

همه فراخوانی‌های SOAP میانای برنامه‌سازی کاربردی باید عنصر <RequestHeader> را در سرصفحه داشته باشند؛ این عنصر در همه WSDLهای سرویس تعریف شده است. کتابخانه‌های مشتری روش‌هایی را برای افزودن این سرصفحه برای شما ارائه می‌دهند، بااستفاده از مقادیری که شما ارائه می‌دهید. در اینجا شرحی از همه عناصر <RequestHeader> ارائه شده است:

عنصر شرح
<networkCode>

کد شبکه شبکه‌ای که به آن پرداخته می‌شود. کدهای شبکه هنگام ایجاد همه درخواست‌ها به‌جز NetworkService.getAllNetworks() و NetworkService.makeTestNetwork() الزامی است.

مطمئن شوید که فقط از کد شبکه‌ای استفاده می‌کنید که برای ورود به سیستم حسابتان دردسترس است. می‌توانید این کد را در وب‌سایت Google Ad Manager برای حسابتان، در صفحه «سرپرست > تنظیمات شبکه» در کنار «کد شبکه» پیدا کنید.
<applicationName> نام رشته‌ای دلخواه که برنامه شما را شناسایی می‌کند. این مورد در فایل‌های گزارش Google نشان داده خواهد شد. برای مثال: «My Inventory Application» یا «App_1».

توجه: هر درخواستی که برنامه شما به Ad Manager API ارسال می‌کند باید شامل یک کد دسترسی OAuth2 باشد. کد را در سرصفحه HTTP به‌صورت Authorization: Bearer YOUR_ACCESS_TOKEN ارسال کنید.

نمونه درخواست

کد زیر نمونه‌ای از فراخوانی درخواست SOAP به getAdUnitsByStatement() است که به‌دنبال ریشه AdUnit می‌گردد.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header>
    <ns1:RequestHeader
         soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
         soapenv:mustUnderstand="0"
         xmlns:ns1="https://www.google.com/apis/ads/publisher/v202608">
      <ns1:networkCode>123456</ns1:networkCode>
      <ns1:applicationName>DfpApi-Java-2.1.0-dfp_test</ns1:applicationName>
    </ns1:RequestHeader>
  </soapenv:Header>
  <soapenv:Body>
    <getAdUnitsByStatement xmlns="https://www.google.com/apis/ads/publisher/v202608">
      <filterStatement>
        <query>WHERE parentId IS NULL LIMIT 500</query>
      </filterStatement>
    </getAdUnitsByStatement>
  </soapenv:Body>
</soapenv:Envelope>

توجه: اگر درخواست SOAP شما باعث Unmarshalling error می‌شود، برای نکته‌های عیب‌یابی به خطاهای رایج مراجعه کنید.

سرصفحه‌های پاسخ

همه پاسخ‌های برگشتی از API شامل عناصر سرصفحه زیر است. به‌عنوان یک روال مطلوب، توصیه می‌کنیم این مقادیر را ثبت کنید.

عنصر شرح
<requestId> این درخواست را به‌طور یکتا شناسایی می‌کند. اگر مشکلی در پشتیبانی دارید، ارسال این شناسه به ما کمک می‌کند درخواستتان را راحت‌تر پیدا کنیم.
<responseTime> زمان سپری‌شده بین دریافت درخواست توسط سرویس وب و ارسال پاسخ.

پاسخ نمونه

کد زیر نمونه‌ای از پاسخ SOAP برای درخواست قبلی را نشان می‌دهد.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <ResponseHeader xmlns="https://www.google.com/apis/ads/publisher/v202608">
      <requestId>xxxxxxxxxxxxxxxxxxxx</requestId>
      <responseTime>1063</responseTime>
    </ResponseHeader>
  </soap:Header>
  <soap:Body>
    <getAdUnitsByStatementResponse xmlns="https://www.google.com/apis/ads/publisher/v202608">
      <rval>
        <totalResultSetSize>1</totalResultSetSize>
        <startIndex>0</startIndex>
        <results>
          <id>2372</id>
          <name>RootAdUnit</name>
          <description></description>
          <targetWindow>TOP</targetWindow>
          <status>ACTIVE</status>
          <adUnitCode>1002372</adUnitCode>
          <inheritedAdSenseSettings>
            <value>
              <adSenseEnabled>true</adSenseEnabled>
              <borderColor>FFFFFF</borderColor>
              <titleColor>0000FF</titleColor>
              <backgroundColor>FFFFFF</backgroundColor>
              <textColor>000000</textColor>
              <urlColor>008000</urlColor>
              <adType>TEXT_AND_IMAGE</adType>
              <borderStyle>DEFAULT</borderStyle>
              <fontFamily>DEFAULT</fontFamily>
              <fontSize>DEFAULT</fontSize>
            </value>
          </inheritedAdSenseSettings>
        </results>
      </rval>
    </getAdUnitsByStatementResponse>
  </soap:Body>
</soap:Envelope>