Ad Manager SOAP API से माइग्रेट करना

Ad Manager SOAP API, Ad Manager के डेटा को पढ़ने, उसमें बदलाव करने, और रिपोर्ट चलाने के लिए, पुराना एपीआई है. अगर माइग्रेट किया जा सकता है, तो हमारा सुझाव है कि 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 के मौजूदा क्रेडेंशियल का इस्तेमाल किया जा सकता है या नए क्रेडेंशियल बनाए जा सकते हैं. दोनों ही विकल्पों के लिए, आपको पहले अपने Google Cloud प्रोजेक्ट में Ad Manager API को चालू करना होगा. ज़्यादा जानकारी के लिए, पुष्टि करना देखें.

अगर क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो सेवा खाते की कुंजी वाली फ़ाइल के पाथ पर, 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 (बीटा वर्शन) की क्वेरी लैंग्वेज, Publisher Query Language (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"
}

एनकोड किया गया यूआरएल

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 के मुकाबले, इसके सिंटैक्स में ये अंतर हैं:

  • Ad Manager API (बीटा वर्शन) में, AND और OR ऑपरेटर केस सेंसिटिव होते हैं. छोटे अक्षरों में लिखे गए 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 (बीटा वर्शन) में, बाइंड वैरिएबल काम नहीं करते. सभी वैल्यू इनलाइन होनी चाहिए.

  • जिन स्ट्रिंग लिटरल में स्पेस होते हैं उन्हें डबल कोट में रैप किया जाना चाहिए, जैसे, "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 पैरामीटर का इस्तेमाल किया जाता है. Ad Manager SOAP API में, LIMIT क्लॉज़ के उलट, पेज का साइज़ न बताने पर, नतीजों का पूरा सेट नहीं दिखता. इसके बजाय, लिस्ट करने के तरीके में, डिफ़ॉल्ट तौर पर 50 पेज साइज़ का इस्तेमाल किया जाता है. यहां दिए गए उदाहरण में, pageSize और pageToken को यूआरएल पैरामीटर के तौर पर सेट किया गया है:

# 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 सिर्फ़ इंटरैक्टिव रिपोर्ट को पढ़ सकता है, उनमें बदलाव कर सकता है, और उन्हें चला सकता है.

रिपोर्टिंग टूल और एपीआई का आईडी स्पेस अलग-अलग होता है. SOAP API में मौजूद SavedQuery के आईडी का इस्तेमाल, REST API में नहीं किया जा सकता.

अगर SavedQuery का इस्तेमाल किया जा रहा है, तो यूज़र इंटरफ़ेस (यूआई) में रिपोर्ट को इंटरैक्टिव रिपोर्ट में माइग्रेट किया जा सकता है. साथ ही, दोनों आईडी स्पेस के बीच मैपिंग बनाई जा सकती है. यूआई में रिपोर्ट माइग्रेट करने के बारे में ज़्यादा जानने के लिए, रिपोर्ट को इंटरैक्टिव रिपोर्ट में माइग्रेट करना लेख पढ़ें.

SOAP से REST enum वैल्यू की पूरी मैपिंग देखने के लिए, रिपोर्ट का रेफ़रंस देखें.

एपीआई के बीच अंतर को समझना

SOAP API और REST API, रिपोर्ट की परिभाषाओं और नतीजों को अलग-अलग तरीके से हैंडल करते हैं:

  • जब किसी रिपोर्ट में सिर्फ़ NAME का अनुरोध किया जाता था, तब SOAP API, नतीजों में उससे जुड़ा ID डाइमेंशन अपने-आप जोड़ देता था. REST API में, नतीजों में शामिल करने के लिए, आपको ReportDefinition में ID डाइमेंशन साफ़ तौर पर जोड़ना होगा.

  • SOAP API में, मेट्रिक के लिए साफ़ तौर पर टाइप तय नहीं किए गए थे. REST API में, डेटा टाइप तय किया जाता है. इसकी जानकारी, Dimension enum वैल्यू में दी गई है. ध्यान दें कि ENUM डाइमेंशन, ओपन enum होते हैं. नतीजों को पार्स करते समय, enum की नई और अनजाने वैल्यू को हैंडल करना ज़रूरी है.

  • SOAP API में, Dimensions और DimensionAttributes को अलग-अलग रखा जाता था. REST API में, Dimension enum को एक साथ रखा जाता है. इसमें दोनों शामिल होते हैं.

  • SOAP API में, डाइमेंशन की संख्या पर कोई सीमा नहीं थी. इंटरैक्टिव रिपोर्ट में, यूआई और एपीआई, दोनों में 10 डाइमेंशन की सीमा होती है. एक ही आईडी स्पेस के हिसाब से ब्रेकडाउन करने वाले डाइमेंशन की गिनती, एक डाइमेंशन के तौर पर की जाती है. उदाहरण के लिए, सीमा की गिनती करते समय, ORDER_NAME, ORDER_ID, और ORDER_START_DATE को शामिल करने पर, इनकी गिनती सिर्फ़ एक डाइमेंशन के तौर पर की जाती है.