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

Ad Manager SOAP API, एक लेगसी एपीआई है. इसकी मदद से, Ad Manager के डेटा को पढ़ा और लिखा जा सकता है. साथ ही, रिपोर्ट भी चलाई जा सकती हैं. अगर माइग्रेट किया जा सकता है, तो हमारा सुझाव है कि आप Ad Manager API (बीटा वर्शन) का इस्तेमाल करें. हालांकि, Ad Manager के SOAP API के वर्शन, उनके सामान्य लाइफ़साइकल के लिए काम करते हैं. ज़्यादा जानकारी के लिए, Ad Manager SOAP API का इस्तेमाल बंद होने का शेड्यूल देखें.

यहां दी गई गाइड में, Ad Manager SOAP एपीआई और 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 Windows

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

फ़िल्टर के बीच अंतर को समझना

Ad Manager API (बीटा) की क्वेरी लैंग्वेज, पब्लिशर क्वेरी लैंग्वेज (PQL) की सभी सुविधाओं के साथ काम करती है. हालांकि, सिंटैक्स में काफ़ी अंतर है.

Order ऑब्जेक्ट की सूची बनाने के इस उदाहरण में, बड़े बदलावों के बारे में बताया गया है. जैसे, बिंड वैरिएबल हटाना, केस-सेंसिटिव ऑपरेटर, और ORDER BY और LIMIT क्लॉज़ को अलग-अलग फ़ील्ड से बदलना:

Ad Manager SOAP API Ad Manager 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>

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