Set tags

Tool Name: airdroid_business_set_tags

Risk Level: 🟠 Medium Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

Summary: Set tags on a device (supports append or overwrite mode).

Prerequisites: DeviceId (device ID) + TagIds (array of tag IDs).

Success Criteria: StatusCode == 200 and ErrorMessage is empty string.

What to Do Next: Use Get All Devices to verify that tags have been set.

Minimal Request Example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "TagIds": [101, 102]
}

Minimal Response Example:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Append Tags (Keep Existing Tags)

When to use: Add new tags to a device while keeping its existing tags.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "TagIds": [101, 102],
  "IsCover": false
}

Recipe 2: Overwrite Tags (Replace All Existing Tags)

When to use: Replace all existing tags on a device with new ones.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "TagIds": [103, 104, 105],
  "IsCover": true
}

Recipe 3: Look Up Tag IDs First Then Set

When to use: You only know the tag names and need to get tag IDs first.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "TagIds": [101, 102],
  "IsCover": false
}

Prerequisite step: Call Get Tag IDs by Tag Names first to convert tag names to IDs.

1. Overview

1.1 Description

Set tags on a specified device. Supports two modes:

• Append mode (IsCover=false): Add new tags to existing ones
• Overwrite mode (IsCover=true): Replace all existing tags with new ones

1.2 When to Use

• Add classification tags to devices (e.g., department, location, usage)
• Batch update device tag classifications
• Reorganize device tag system

1.3 Execution Mode and Response

This operation is synchronous and returns results immediately.

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier.

• Type: string
• Format: Non-empty string
• Source:

How to obtain:

1. Via Get All Devices tool - use the device_id field from the response
2. Via Get a Device by Name tool - exact name query

The device_id field from the output can be used directly as this parameter.

• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

`TagIds`

Array of tag IDs to set.

• Type: number-array
• Format:
  • JSON array containing one or more integer tag IDs
  • Maximum 5 tags
• Source:

How to obtain:

Via Get Tag IDs by Tag Names tool to convert tag names to IDs

• Example:

  [101, 102, 103]

`IsCover`

Whether to overwrite existing tags.

• Type: boolean
• Available values:
  • false (default): Append mode — adds new tags to existing ones
  • true: Overwrite mode — replaces all existing tags with the new ones
• Notes:
  • In append mode, already existing tags will not be duplicated
  • In overwrite mode, all existing tags are removed, keeping only the newly set tags
• Example:

  false

2.3 Parameter Combination Logic

• DeviceId and TagIds are both required
• IsCover is optional, defaults to false (append mode)
• TagIds can contain a maximum of 5 tag IDs

3. Outputs

3.1 Response Example

Success response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

{
  "StatusCode": -1,
  "ErrorMessage": "DeviceId is required. Obtain via 'Get All Devices' or 'Get A Device By Name' tool."
}

3.2 Field Descriptions

4. Examples

4.1 Basic Example: Append Tags

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "TagIds": [101, 102],
  "IsCover": false
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Overwrite All Tags

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "TagIds": [103, 104, 105],
  "IsCover": true
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Error Example: Tag Count Exceeded

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "TagIds": [101, 102, 103, 104, 105, 106]
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": "Maximum 5 tags allowed per device"
}

5. Error Handling

5.1 AB Three-Layer Error Codes

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Single device operation: This tool can only set tags for one device at a time; batch setting requires loop calls
• Tag count limit: Maximum 5 tags per device; plan your tag system accordingly

6.2 Security Considerations

🟡 Write operation:

• Overwrite risk: Using IsCover=true removes all existing tags; use with caution
• Confirm target: Verify DeviceId is correct before setting
• Validate tag IDs: Use Get Tag IDs by Tag Names to verify tag IDs exist

6.3 Idempotency

IsCover=true (overwrite mode): Naturally idempotent. Multiple calls produce the same result.

IsCover=false (append mode): Conditionally idempotent. Already existing tags will not be duplicated and produce no side effects.

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

8. Tool Chains

8.1 Set Tags by Tag Names

Scenario: You know the tag names and need to set these tags on a device.

Tool Chain:

Get Tag IDs by Tag Names → Set Tags

Steps:

1. Call Get Tag IDs by Tag Names to get tag IDs
2. Extract tag ID array from TagIds.found
3. Call Set Tags to assign tags to the device

Example:

Input: TagNames = ["Sales", "VIP"]
Output: found = {"Sales": 101, "VIP": 102}
Use: TagIds = [101, 102] to call Set Tags

8.2 Find Device by Name and Set Tags

Scenario: You know the device name and tag names, need to set tags.

Tool Chain:

Get a Device by Name + Get Tag IDs by Tag Names → Set Tags

Steps:

1. Call Get a Device by Name in parallel to get DeviceId
2. Call Get Tag IDs by Tag Names in parallel to get TagIds
3. Use the obtained DeviceId and TagIds to call Set Tags

8.3 Batch Set Same Tags on Multiple Devices

Scenario: Set the same tags on multiple devices.

Tool Chain:

Get Tag IDs by Tag Names → Get All Devices → [Loop] Set Tags

Steps:

1. Call Get Tag IDs by Tag Names to get tag IDs
2. Call Get All Devices to get target device list
3. Iterate through devices and call Set Tags for each one

8.4 Set and Verify

Scenario: Set tags and confirm the operation succeeded.

Tool Chain:

Set Tags → Get All Devices (verify)

Steps:

1. Call Set Tags to set tags
2. Confirm ErrorMessage is empty
3. Call Get All Devices to query the device and confirm the tags field has been updated

Appendix Reference:

• Field Reference: https://www.goinsight.ai/tools/field-reference/
• Error Code Quick Reference: https://www.goinsight.ai/tools/error-codes/