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 के तरीकों के लिए मैपिंग का उदाहरण दिखाया गया है:

एसओएपी तरीका	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". स्ट्रिंग लिटरल को रैप करने के लिए, सिंगल कोट का इस्तेमाल नहीं किया जा सकता.

ORDER BY क्लॉज़ हटाना

Ad Manager API (बीटा वर्शन) में, क्रम से लगाने का तरीका बताना ज़रूरी नहीं है. अगर आपको नतीजों के सेट के लिए क्रम तय करना है, तो PQL ORDER BY क्लॉज़ हटाएं और इसके बजाय orderBy फ़ील्ड सेट करें:

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

अहम जानकारी: Ad Manager SOAP API, पेज नंबर के हिसाब से नतीजे दिखाने की सुविधा को लगातार बनाए रखने के लिए, हमेशा ORDER BY क्लॉज़ को शामिल करने का सुझाव देता है. हालांकि, Ad Manager API (Beta) पेज नंबर के हिसाब से नतीजे दिखाने की सुविधा को लगातार बनाए रखता है.

ऑफ़सेट से पेज नंबर के हिसाब से नतीजे दिखाने वाले टोकन पर माइग्रेट करना

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 API और REST API, रिपोर्ट की परिभाषाओं और नतीजों को अलग-अलग तरीके से हैंडल करते हैं. इनके बीच ये अंतर हैं:

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

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

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

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