# ऑब्जेक्ट टैग API (बीटा)

ऑब्जेक्ट टैग किसी उपयोगकर्ता के बारे में संरचित डेटा को एक ही टैग में संग्रहीत करते हैं। `Object` प्रकार का टैग नामित फ़ील्ड वाला एक ऑब्जेक्ट रखता है, जैसे अपने `amount` और `status` के साथ अंतिम `order`। `ObjectList` प्रकार का टैग ऐसे ऑब्जेक्ट्स की एक ऐरे रखता है, जैसे सभी `orders`। आप फ़ील्ड एक बार परिभाषित करते हैं, टैग API के माध्यम से मान लिखते और पढ़ते हैं, और फ़ील्ड मानों के आधार पर सेगमेंट बनाते हैं।

<Aside type="caution" title="बीटा">
ऑब्जेक्ट टैग बीटा में हैं और अनुरोध पर उपलब्ध हैं। अपने खाते के लिए इन्हें सक्षम करने के लिए [Pushwoosh सपोर्ट](https://help.pushwoosh.com/hc/en-us/requests/new) से संपर्क करें। बीटा के दौरान ऑब्जेक्ट टैग केवल API के माध्यम से काम करते हैं:

- कंट्रोल पैनल में ऑब्जेक्ट टैग के लिए कोई स्क्रीन नहीं है।
- ऑब्जेक्ट टैग के फ़ील्ड संदेश सामग्री में नहीं डाले जा सकते।
- Customer Journey ऑब्जेक्ट टैग का समर्थन नहीं करता।
</Aside>

## ऑब्जेक्ट टैग कैसे काम करते हैं

ऑब्जेक्ट टैग में एक स्कीमा और एक मान होता है। स्कीमा टैग का नाम और फ़ील्ड की सूची है, जिसमें हर फ़ील्ड का अपना स्केलर प्रकार होता है। मान फ़ील्ड में, हर उपयोगकर्ता के लिए अलग से, संग्रहीत होता है।

- **फ़ील्ड।** हर फ़ील्ड `<object>.<field>` नाम वाला एक टैग है, उदाहरण के लिए `order.amount`। आप फ़ील्ड के आधार पर सेगमेंट बनाते हैं, और `Object` टैग का फ़ील्ड इसी नाम से लिख सकते हैं।
- **`Object` मान।** प्रति उपयोगकर्ता एक ऑब्जेक्ट, उदाहरण के लिए `"order": {"amount": 120, "status": "paid"}`।
- **`ObjectList` मान।** समान फ़ील्ड वाले ऑब्जेक्ट्स की एक ऐरे, उदाहरण के लिए `"orders": [{"amount": 120, "status": "paid"}, {"amount": 50}]`।

ऑब्जेक्ट टैग हमेशा User-specific होते हैं, यानी मान उपयोगकर्ता का होता है, किसी एक डिवाइस का नहीं, और उपयोगकर्ता के सभी डिवाइस पर कॉपी किया जाता है। सामान्य टैग के लिए [टैग्स API](/hi/developer/api-reference/tags/) देखें।

## स्कीमा नियम

जब आप ऑब्जेक्ट टैग बनाते हैं या फ़ील्ड जोड़ते हैं, तो Pushwoosh इन नियमों की जांच करता है:

- ऑब्जेक्ट और फ़ील्ड के नामों में केवल लैटिन अक्षर, अंक और `_` होते हैं।
- पूरा फ़ील्ड नाम `<object>.<field>` 64 वर्णों या उससे छोटा होता है।
- एक ऑब्जेक्ट टैग में 1 से 20 फ़ील्ड होते हैं। फ़ील्ड नाम केस-इनसेंसिटिव होते हैं, इसलिए `Amount` और `amount` एक ही फ़ील्ड हैं।
- फ़ील्ड का प्रकार इनमें से एक होता है: `INTEGER`, `STRING`, `LIST`, `DATE`, `BOOLEAN`, `PRICE`, `VERSION`। टाइमज़ोन फ़ील्ड और नेस्टेड ऑब्जेक्ट समर्थित नहीं हैं।
- फ़ील्ड ऐसा नाम नहीं ले सकता जो किसी दूसरे टैग के पास पहले से है। यदि टैग `order.note` मौजूद है, तो `order` में फ़ील्ड `note` जोड़ना `tag order.note already exists` के साथ विफल होता है।
- ऑब्जेक्ट टैग अपना अंतिम फ़ील्ड नहीं खो सकता। इसके बजाय ऑब्जेक्ट टैग हटाएं।
- उपयोग में मौजूद फ़ील्ड या ऑब्जेक्ट टैग को हटाया नहीं जा सकता। त्रुटि बताती है कि इसका उपयोग कहां होता है, उदाहरण के लिए `field is in use: segment Big buyers, in-app Spring sale`। टैग को संदर्भित करने वाले सेगमेंट, इन-ऐप, चल रहे Customer Journey कैंपेन, प्रीसेट, ईमेल टेम्पलेट और अन्य आइटम उपयोग के रूप में गिने जाते हैं।

## स्कीमा प्रबंधित करें

नीचे दी गई REST विधियों से ऑब्जेक्ट टैग बनाएं और बदलें। `/json/1.3/addTag` का उपयोग केवल सामान्य टैग के लिए करें, क्योंकि यह फ़ील्ड परिभाषित नहीं कर सकता।

### बेस URL

```
https://rpc-api.svc-nue.pushwoosh.com
```

### प्रमाणीकरण

हर अनुरोध में आपके [सर्वर API टोकन](/hi/developer/api-reference/api-access-token/#server-api-token) के साथ `Authorization` हेडर शामिल होना चाहिए। डिवाइस API टोकन को HTTP 403 `a device API token cannot call this method, use an account API token` मिलता है।

```
Authorization: Api YOUR_API_TOKEN
```

### एंडपॉइंट्स

ये विधियां ऑब्जेक्ट टैग के स्कीमा को प्रबंधित करती हैं:

| विधि | पाथ | विवरण |
| :---- | :---- | :---- |
| `POST` | `/api/tags` | अपने फ़ील्ड के साथ ऑब्जेक्ट टैग बनाएं |
| `GET` | `/api/tags/{name}` | अपने फ़ील्ड के साथ ऑब्जेक्ट टैग प्राप्त करें |
| `GET` | `/api/tags` | टैग सूचीबद्ध करें। ऑब्जेक्ट टैग अपने `fields` के साथ आता है, और फ़ील्ड अलग टैग के रूप में सूचीबद्ध नहीं होते |
| `POST` | `/api/tags/{name}/fields` | फ़ील्ड जोड़ें |
| `DELETE` | `/api/tags/{name}/fields/{field}` | फ़ील्ड हटाएं |
| `DELETE` | `/api/tags/{name}` | सभी फ़ील्ड के साथ ऑब्जेक्ट टैग हटाएं |

`POST /api/tags` और दोनों फ़ील्ड विधियां बदलाव के बाद का ऑब्जेक्ट टैग `{"tag": {...}}` में लपेटकर लौटाती हैं। `DELETE /api/tags/{name}` `{}` लौटाता है।

यदि आपके खाते के लिए ऑब्जेक्ट टैग सक्षम नहीं हैं, तो ऑब्जेक्ट प्रकार के साथ `POST /api/tags` और दोनों फ़ील्ड विधियां HTTP 403 `object tags are not enabled for the account` के साथ विफल होती हैं। `GET /api/tags/{name}` और `DELETE /api/tags/{name}` HTTP 404 `tag not found` लौटाते हैं, और `GET /api/tags` ऑब्जेक्ट टैग सूचीबद्ध नहीं करता। ऑब्जेक्ट टैग सक्षम किए बिना आप एक भी नहीं बना सकते, इसलिए मान लिखने के लिए कुछ नहीं होता।

<span id="create-an-object-tag" />

### ऑब्जेक्ट टैग बनाएं

`POST` `/api/tags`

##### अनुरोध बॉडी

| नाम | प्रकार | विवरण |
| :---- | :---- | :---- |
| name\* | string | ऑब्जेक्ट टैग का नाम। |
| type\* | string | एक ऑब्जेक्ट के लिए `OBJECT` या ऑब्जेक्ट्स की सूची के लिए `OBJECT_LIST`। |
| fields\* | array | ऑब्जेक्ट के फ़ील्ड, 1 से 20 तक। |
| fields[].name\* | string | फ़ील्ड का नाम। फ़ील्ड टैग `<name>.<fields[].name>` बन जाता है। |
| fields[].type\* | string | फ़ील्ड का प्रकार: `INTEGER`, `STRING`, `LIST`, `DATE`, `BOOLEAN`, `PRICE` या `VERSION`। |

```json title="उदाहरण"
{
  "name": "orders",
  "type": "OBJECT_LIST",
  "fields": [
    { "name": "amount", "type": "INTEGER" },
    { "name": "status", "type": "STRING" }
  ]
}
```

```json title="प्रतिक्रिया"
{
  "tag": {
    "name": "orders",
    "type": "OBJECT_LIST",
    "system": false,
    "user_specific": true,
    "has_right_ace_modify": true,
    "fields": [
      { "name": "amount", "type": "INTEGER" },
      { "name": "status", "type": "STRING" }
    ]
  }
}
```

`user_specific` के मान की परवाह किए बिना टैग User-specific के रूप में बनाया जाता है। `GET /api/tags/{name}` वही ऑब्जेक्ट `tag` रैपर के बिना लौटाता है। फ़ील्ड नाम के अनुसार क्रमबद्ध होते हैं।

### फ़ील्ड जोड़ें

`POST` `/api/tags/{name}/fields`

```json title="उदाहरण: POST /api/tags/orders/fields"
{
  "field": { "name": "note", "type": "STRING" }
}
```

आप नया फ़ील्ड तुरंत पूरे टैग मान के हिस्से के रूप में लिख सकते हैं। यदि ऑब्जेक्ट टैग में पहले से 20 फ़ील्ड हैं या पूरे फ़ील्ड नाम वाला टैग मौजूद है, तो फ़ील्ड जोड़ना विफल होता है, [त्रुटियाँ](#errors) देखें।

### फ़ील्ड हटाएं

`DELETE` `/api/tags/{name}/fields/{field}`

उदाहरण के लिए, `DELETE /api/tags/orders/fields/note` फ़ील्ड `orders.note` को हटाता है। आप अंतिम फ़ील्ड या उपयोग में मौजूद फ़ील्ड को नहीं हटा सकते, [त्रुटियाँ](#errors) देखें।

<span id="errors" />

### त्रुटियाँ

त्रुटियाँ `{"code": <n>, "message": "...", "details": [...]}` प्रारूप में आती हैं। जब आप ऑब्जेक्ट टैग बनाते हैं, तो 400 संदेश `validate: ` से शुरू होते हैं।

| HTTP स्थिति | संदेश | कारण |
| :---- | :---- | :---- |
| 400 | `object tag and field names must contain only letters, digits and underscores` | किसी नाम में कोई अन्य वर्ण है। |
| 400 | `an object tag needs 1 to 20 fields` | बनाते समय कोई फ़ील्ड नहीं या 20 से अधिक फ़ील्ड। |
| 400 | `an object tag has at most 20 fields` | ऑब्जेक्ट टैग में पहले से 20 फ़ील्ड हैं। |
| 400 | `field <name> is given twice` | केस को अनदेखा करते हुए, दो फ़ील्ड का नाम एक जैसा है। |
| 400 | `<object>.<field>: object and field names together cannot be longer than 64 characters` | पूरा फ़ील्ड नाम बहुत लंबा है। |
| 400 | `<object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE or VERSION` | असमर्थित फ़ील्ड प्रकार। |
| 400 | `an object tag needs at least one field; delete the object tag instead` | आपने अंतिम फ़ील्ड हटाने की कोशिश की। |
| 400 | `field is in use: ...`, `tag is in use: ...` | फ़ील्ड या ऑब्जेक्ट टैग का उपयोग सेगमेंट, इन-ऐप, Customer Journey कैंपेन या अन्य आइटम में होता है। |
| 403 | `object tags are not enabled for the account` | खाते के लिए ऑब्जेक्ट टैग सक्षम नहीं हैं। |
| 403 | `a device API token cannot call this method, use an account API token` | अनुरोध डिवाइस API टोकन का उपयोग करता है। |
| 404 | `tag not found` | `GET` या `DELETE /api/tags/{name}`: ऐसा कोई टैग नहीं है, नाम एक फ़ील्ड है, या ऑब्जेक्ट टैग सक्षम नहीं हैं। |
| 404 | `object tag not found`, `field not found` | फ़ील्ड विधियां: ऐसा कोई ऑब्जेक्ट टैग या फ़ील्ड नहीं है। |
| 409 | `tag already exists` | ऑब्जेक्ट टैग के नाम वाला टैग मौजूद है। |
| 409 | `tag <object>.<field> already exists` | फ़ील्ड के पूरे नाम वाला टैग मौजूद है। |

## मान लिखें

ऑब्जेक्ट टैग के मान [`/setTags`](/hi/developer/api-reference/device-api/#settags) और [`/bulkSetTags`](/hi/developer/api-reference/audience-api/#bulksettags) से लिखें। ये विधियां अपना प्रमाणीकरण बनाए रखती हैं: `/setTags` `Authorization: Token` हेडर में डिवाइस API टोकन लेता है, और `/bulkSetTags` `auth` में API एक्सेस टोकन लेता है। `Object` मान को JSON ऑब्जेक्ट के रूप में और `ObjectList` मान को ऑब्जेक्ट्स की ऐरे के रूप में भेजें:

```json title="उदाहरण: /json/1.3/setTags"
{
  "request": {
    "application": "XXXXX-XXXXX",
    "userId": "user_42",
    "tags": {
      "order": { "amount": 120, "status": "paid" },
      "orders": [
        { "amount": 120, "status": "paid" },
        { "amount": 50 }
      ]
    }
  }
}
```

यदि आप HWID द्वारा मान सेट करते हैं, तो वह उस डिवाइस के उपयोगकर्ता पर संग्रहीत होता है।

हर फ़ील्ड अपने प्रकार के प्रारूप में मान लेता है:

| फ़ील्ड प्रकार | उदाहरण मान |
| :---- | :---- |
| `INTEGER` | `120` |
| `STRING` | `"paid"` |
| `LIST` | `["gift", "express"]` |
| `DATE` | `"2026-10-02 22:11"` (UTC), `"2026-10-02"`, या सेकंड में Unix टाइमस्टैम्प |
| `BOOLEAN` | `true` या `false` |
| `PRICE` | `19.95` |
| `VERSION` | `"1.0.0"` |

### लिखने से पूरा मान बदल जाता है

हर बार लिखने पर ऑब्जेक्ट टैग का संग्रहीत मान बदल दिया जाता है:

- नए मान में मौजूद न होने वाला फ़ील्ड हटा दिया जाता है। `null` के रूप में भेजा गया फ़ील्ड भी हटा दिया जाता है।
- `null`, `[]` या `""` पूरा मान हटा देता है।
- `{}` `Object` टैग के सभी फ़ील्ड हटा देता है।
- जो कुंजी ऑब्जेक्ट का फ़ील्ड नहीं है, उसे छोड़ दिया जाता है।
- यदि कोई फ़ील्ड मान फ़ील्ड प्रकार से मेल नहीं खाता, तो टैग का पूरा मान अस्वीकार कर दिया जाता है और संग्रहीत मान वैसा ही रहता है।

`/setTags` अपनी प्रतिक्रिया में अस्वीकृत मान की रिपोर्ट नहीं करता। परिणाम [`/getTags`](#read-values) से जांचें या `/bulkSetTags` का उपयोग करें, जो हर टैग के लिए परिणाम रिपोर्ट करता है।

### Object का एक फ़ील्ड लिखें

`Object` टैग का एक फ़ील्ड उसके पूरे नाम से लिखें। `increment` और [`/setTags`](/hi/developer/api-reference/device-api/#settags) के अन्य ऑपरेशन फ़ील्ड पर काम करते हैं:

```json
"tags": {
  "order.status": "shipped",
  "order.amount": { "operation": "increment", "value": 5 }
}
```

`ObjectList` टैग का फ़ील्ड अलग से नहीं लिखा जा सकता, क्योंकि यह स्पष्ट नहीं है कि कौन-सा एलिमेंट बदलना है। `/setTags` ऐसे मान को अनदेखा करता है। इसके बजाय पूरी सूची भेजें।

### ऑब्जेक्ट टैग स्वचालित रूप से नहीं बनते

ऐसे टैग के लिए ऑब्जेक्ट या ऑब्जेक्ट्स की ऐरे वाला मान, जो मौजूद नहीं है, छोड़ दिया जाता है। टैग ऑटो-क्रिएशन ऑब्जेक्ट टैग नहीं बनाता, इसलिए पहले [`POST /api/tags`](#create-an-object-tag) से स्कीमा बनाएं।

### bulkSetTags परिणाम

`detailed=true` के साथ, [`/bulkSetTags` स्थिति](/hi/developer/api-reference/audience-api/#bulksettags-status) ऑब्जेक्ट टैग के लिए `ok`, `tag not found` और `wrong value. expect :<type>` के अलावा इनमें से एक परिणाम लौटाता है:

| परिणाम | कारण |
| :---- | :---- |
| `object tags are stored on the user only` | ऑब्जेक्ट टैग User-specific नहीं है। |
| `cannot load the fields of the object` | Pushwoosh ऑब्जेक्ट टैग के फ़ील्ड नहीं पढ़ सका। |
| `wrong value. expect an object (a map) or, for a list of objects, an array of maps` | मान ऑब्जेक्ट टैग में फ़िट नहीं होता, या कोई फ़ील्ड मान अपने प्रकार से मेल नहीं खाता। |
| `a field of a list of objects cannot be set on its own, set the whole list` | मान `ObjectList` टैग के फ़ील्ड पर सेट किया गया है। |

<span id="read-values" />

## मान पढ़ें

[`/getTags`](/hi/developer/api-reference/device-api/#gettags) `Object` मान को JSON ऑब्जेक्ट के रूप में और `ObjectList` मान को ऑब्जेक्ट्स की ऐरे के रूप में लौटाता है:

```json title="प्रतिक्रिया"
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "result": {
      "order": { "amount": 120, "status": "paid" },
      "orders": [
        { "amount": 120, "status": "paid" },
        { "amount": 50 }
      ]
    }
  }
}
```

फ़ील्ड मान `/getTags` में सामान्य टैग मानों की तरह ही लौटाए जाते हैं: Date सेकंड में Unix टाइमस्टैम्प के रूप में, Price `"120.00"` जैसी स्ट्रिंग के रूप में, और Boolean `1` या `0` के रूप में।

<span id="segment-by-fields" />

## फ़ील्ड के आधार पर सेगमेंट करें

सेगमेंट की शर्तें फ़ील्ड पर सेट करें, ऑब्जेक्ट टैग पर नहीं। [सेगमेंटेशन भाषा](/hi/developer/api-reference/segmentation-filters-api/segmentation-language/) में फ़ील्ड बिंदु वाले नाम का एक टैग है, और यह अपने प्रकार के ऑपरेटर लेता है:

```
AT("XXXXX-XXXXX", "order.amount", gte, 100)
```

ऑब्जेक्ट टैग पर ही लगाई गई शर्त `object tag has no value of its own, use one of its fields` के साथ विफल होती है।

### ObjectList पर शर्तें

`ObjectList` टैग के फ़ील्ड पर शर्त किसी उपयोगकर्ता से तब मेल खाती है, जब सूची का कम से कम एक एलिमेंट शर्त में फ़िट होता है। AND से जुड़ी, एक ही सूची के फ़ील्ड पर शर्तें एक ही एलिमेंट से मेल खानी चाहिए:

```
AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")
```

इस सेगमेंट में वे उपयोगकर्ता हैं जिनका कम से कम एक ऑर्डर 100 या उससे अधिक का भी है और paid भी है। एक बड़े अवैतनिक ऑर्डर और एक छोटे भुगतान किए गए ऑर्डर वाला उपयोगकर्ता मेल नहीं खाता। OR से जुड़ी शर्तों का एक ही एलिमेंट से मेल खाना ज़रूरी नहीं है। दो अलग-अलग सूचियों पर शर्तें हर सूची पर अलग से जांची जाती हैं।

`ObjectList` टैग के फ़ील्ड पर कुछ ऑपरेटर अलग तरह से काम करते हैं:

- **`notset`।** सूची के किसी भी एलिमेंट में इस फ़ील्ड का मान नहीं है। सूची के बिना उपयोगकर्ता भी मेल खाता है।
- **`noteq`।** कम से कम एक एलिमेंट में इस फ़ील्ड का मान है, और वह मान दिए गए मान से अलग है। फ़ील्ड के बिना एलिमेंट नहीं गिने जाते। `paid` और `new` स्थिति वाले ऑर्डर वाला उपयोगकर्ता `noteq "paid"` से मेल खाता है।
- **List फ़ील्ड पर `notin`।** किसी भी एलिमेंट में दिए गए मानों में से कोई भी मान नहीं है।
- **दूसरे प्रकार के फ़ील्ड पर `notin`।** कम से कम एक एलिमेंट में इस फ़ील्ड का ऐसा मान है जो दिए गए मानों में नहीं है।

List फ़ील्ड पर `notset` और `notin` AND से जुड़ी अन्य शर्तों के साथ एक ही एलिमेंट से बंधे नहीं होते।

## ऑब्जेक्ट टैग वाले सेगमेंट निर्यात करें

[`/exportSegment`](/hi/developer/api-reference/segmentation-filters-api/#exportsegment) ऑब्जेक्ट टैग के फ़ील्ड निर्यात करता है:

- **CSV।** हर फ़ील्ड `<object>.<field>` नाम वाला एक अलग कॉलम है, और ऑब्जेक्ट टैग को खुद कोई कॉलम नहीं मिलता। ObjectList का फ़ील्ड सभी एलिमेंट में मौजूद सभी अलग-अलग मानों को JSON ऐरे के रूप में रखता है, ठीक List टैग की तरह: `["120","50"]`।
- **`json` और `json_each_line`।** `Object` टैग के फ़ील्ड `<object>.<field>` नाम वाले अलग टैग के रूप में आते हैं। `ObjectList` टैग `tags` में एक एंट्री के रूप में आता है, जिसके एलिमेंट `object_list.items` में होते हैं। हर एलिमेंट अपने फ़ील्ड छोटे नामों से सूचीबद्ध करता है, और हर फ़ील्ड अपना मान अपने प्रकार के नाम वाली कुंजी के तहत रखता है: `integer`, `string`, `list`, `date`, `boolean`, `price` या `version`। इंटीजर मान स्ट्रिंग के रूप में आते हैं:

```json
{
  "name": "orders",
  "object_list": {
    "items": [
      { "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] },
      { "fields": [{ "name": "amount", "integer": "50" }] }
    ]
  }
}
```

यदि `tagsList` किसी ऑब्जेक्ट टैग का नाम देता है, तो उसके सभी फ़ील्ड निर्यात किए जाते हैं।