हमारे प्रॉडक्ट के बारे में चर्चा करने और सुझाव/राय देने के लिए, Google विज्ञापन और मेज़रमेंट कम्यूनिटी सर्वर में Ad Manager के आधिकारिक Discord चैनल से जुड़ें.

Google आपकी पसंदीदा भाषा में कॉन्टेंट का अनुवाद करने के लिए, एआई टेक्नोलॉजी का इस्तेमाल करता है. एआई से मिले अनुवादों में गलतियां हो सकती हैं.

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 में, एक ही इकाई को पढ़ने के तरीके भी होते हैं. इसके अलावा, SOAP API में एक perform<Entity>Action तरीके का इस्तेमाल करने वाली स्टेट चेंज कार्रवाइयों के लिए, अब REST API में हर कार्रवाई के टाइप के लिए अलग-अलग तरीके उपलब्ध हैं.

यहां दी गई टेबल में, Order तरीकों के लिए मैपिंग का एक उदाहरण दिखाया गया है:

SOAP मेथड	REST के तरीके
`createOrders`	`networks.orders.batchCreate`
`getOrdersByStatement`	`networks.orders.get` `networks.orders.list`
`updateOrders`	`networks.orders.batchUpdate`
`performOrderAction`	कार्रवाई के हर टाइप के लिए एक तरीका. उदाहरण के लिए: `networks.orders.batchApprove` `networks.orders.batchPause` `networks.orders.batchResume`

स्टेटस में बदलाव करने वाले ऐक्शन के जवाब

SOAP API में, perform<Entity>Action ने UpdateResult ऑब्जेक्ट दिखाया. इसमें numChanges फ़ील्ड से पता चलता था कि कितनी इकाइयों में बदलाव किया गया है. Ad Manager API (बीटा वर्शन) में, बैच ऐक्शन वाले तरीके, खाली रिस्पॉन्स ऑब्जेक्ट दिखाते हैं. यह देखने के लिए कि कार्रवाई पूरी हुई या नहीं, यह देखें कि एचटीटीपी 200 OK स्टेटस क्या है या क्लाइंट लाइब्रेरी में कोई अपवाद तो नहीं है.

सेवाओं का नाम बदला गया और उन्हें अलग-अलग किया गया

Ad Manager API में, कुछ सेवाओं के नाम बदल दिए गए हैं या उन्हें अलग-अलग कर दिया गया है:

SOAP सेवा	REST रिसॉर्स / सेवा
`InventoryService`	`networks.adUnits`
`MobileApplicationService`	`networks.applications`
`CustomTargetingService`	`networks.customTargetingKeys` `networks.customTargetingValues`

पुष्टि करें

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 SOAP API में, इकाइयों की पहचान अंकों वाले Long आईडी से की जाती है. SOAP में मौजूद इकाई के संबंध भी इन संख्या वाले आईडी का रेफ़रंस देते हैं.

Ad Manager API में, इकाइयों की पहचान स्टैंडर्ड संसाधन के नामों से की जाती है. इन्हें स्ट्रिंग के तौर पर फ़ॉर्मैट किया जाता है:

networks/{networkCode}/{collection}/{id}

उदाहरण के लिए, नेटवर्क 123 में मौजूद 123456 आईडी वाले ऑर्डर का संसाधन नाम networks/123/orders/123456 है.

कोड माइग्रेट करते समय:

एक इकाई से जुड़े तरीकों और बैच ऐक्शन के तरीकों में, संख्या वाले आईडी के बजाय संसाधन के नाम वाली स्ट्रिंग का इस्तेमाल किया जाता है.
इकाई के संबंध और फ़ॉरेन की के रेफ़रंस, संसाधन के नामों का इस्तेमाल करते हैं. उदाहरण के लिए, Order.advertiserId के बजाय Order.advertiser networks/123/companies/456 है.
आईडी स्पेस में कोई बदलाव नहीं किया गया है. यह SOAP जैसा ही है. संसाधन के नाम के आखिरी सेगमेंट से, संख्या वाला आईडी निकाला जा सकता है.

अपडेट मास्क के बारे में जानकारी

Ad Manager SOAP API में, अपडेट करने के तरीकों से पूरी इकाई के ऑब्जेक्ट स्वीकार किए जाते थे. साथ ही, इससे बदले गए सभी फ़ील्ड अपडेट हो जाते थे.

Ad Manager API में, अपडेट करने के लिए अपडेट मास्क का इस्तेमाल किया जाता है. अपडेट मास्क यह कंट्रोल करता है कि अपडेट के दौरान किन फ़ील्ड में बदलाव किया जाए:

सिर्फ़ updateMask में दिए गए फ़ील्ड में बदलाव किया जाता है. मास्क से हटाए गए फ़ील्ड में कोई बदलाव नहीं होता.
अगर आपने updateMask की वैल्यू नहीं दी है, तो अनुरोध में मौजूद सभी फ़ील्ड अपडेट हो जाएंगे.

ज़्यादा जानकारी के लिए, फ़ील्ड मास्क देखें.

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

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

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 में फ़ील्ड के नाम, स्टैंडर्ड REST और Google Cloud के उन नियमों का पालन करते हैं जो SOAP से अलग हैं:

डिसप्ले नेम: Ad Manager API में, SOAP name फ़ील्ड का नाम बदलकर displayName कर दिया गया है. उदाहरण के लिए, Order.name अब Order.displayName है और AdUnit.name अब AdUnit.displayName है.
टाइमस्टैंप: SOAP DateTime फ़ील्ड, जैसे कि lastModifiedDateTime और startDateTime को RFC 3339 टाइमस्टैंप स्ट्रिंग से बदल दिया जाता है. updateTime और startTime.
बूलियन: बूलियन फ़ील्ड में is जैसे प्रीफ़िक्स नहीं होते. उदाहरण के लिए, isArchived अब archived है.

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

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 (Beta) से अनुरोध की गई पेज साइज़ से कम नतीजे मिल सकते हैं. भले ही, अतिरिक्त पेज मौजूद हों. 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 में, आपको नतीजों में शामिल करने के लिए ID डाइमेंशन को ReportDefinition में साफ़ तौर पर जोड़ना होगा.
SOAP API में मेट्रिक के लिए, टाइप तय नहीं किए गए थे. REST API, Metric और Dimension एनम वैल्यू में बताए गए डेटा टाइप को तय करता है. ध्यान दें कि ENUM डाइमेंशन, ओपन एनम होते हैं. नतीजों को पार्स करते समय, आपको नई और अज्ञात enum वैल्यू को मैनेज करना होगा.
SOAP API ने Dimensions और DimensionAttributes को अलग कर दिया है. REST API में एक यूनिफ़ाइड Dimension enum होता है, जिसमें दोनों शामिल होते हैं.
SOAP API में डाइमेंशन की संख्या पर कोई पाबंदी नहीं थी. इंटरैक्टिव रिपोर्ट में, यूज़र इंटरफ़ेस (यूआई) और एपीआई, दोनों में 10 डाइमेंशन इस्तेमाल किए जा सकते हैं. एक ही आईडी स्पेस के हिसाब से ब्रेक डाउन किए गए डाइमेंशन को एक डाइमेंशन के तौर पर गिना जाता है. उदाहरण के लिए, सीमा तय करते समय सिर्फ़ ORDER_NAME, ORDER_ID, और ORDER_START_DATE को शामिल करने पर, इन्हें एक डाइमेंशन माना जाता है.

गड़बड़ियां ठीक करना

SOAP API में, गड़बड़ियों को SOAP फ़ॉल्ट के तौर पर दिखाया जाता था. साथ ही, उन्हें ApiException का इस्तेमाल करके ठीक किया जाता था. इसमें सेवा के हिसाब से गड़बड़ी के कोड दिए जाते थे.

Ad Manager API, Google Cloud के स्टैंडर्ड आरपीसी और एचटीटीपी गड़बड़ी के मॉडल का इस्तेमाल करता है:

गड़बड़ियों के लिए, स्टैंडर्ड एचटीटीपी स्टेटस कोड मिलते हैं. जैसे, 400 INVALID_ARGUMENT, 404 NOT_FOUND या 403 PERMISSION_DENIED.
एपीआई से जुड़ी गड़बड़ियों की पूरी जानकारी, जैसे कि फ़ील्ड के नियमों का उल्लंघन करने की वजहें, error payload की गड़बड़ी की जानकारी में दिखती हैं.