Tool Name: airdroid_business_qiniu_file_batch_upload
Risk Level: 🟡 Write
Execution Mode: ⏳ Asynchronous (returns OperationLogId)
Category: File Management
Quick Start (Copy & Use)
Summary: Issue per-device Qiniu upload tokens and command Android devices to upload local files matching LocalDir and FileNamePattern.
Prerequisites: AirDroid Business OAuth2 on the node; Qiniu AccessKey / SecretKey on the node; Bucket, UploadHost (https:// upload domain), DeviceInfos (1–100 devices, unique device_id, each with device_name), LocalDir, FileNamePattern.
Key constraints (read first):
- Android only — Windows devices are not supported on this upload path.
- LocalDir scans only that folder — subfolders are not recursed.
- Overwrite defaults to true — when true, DedupDays is ignored.
- StatusCode == 200 and empty ErrorMessage means the batch was accepted and you received OperationLogId — not that every file finished uploading on devices.
Success Criteria: StatusCode == 200 and ErrorMessage is empty; save OperationLogId (string) and poll Search File Batch Upload Results until terminal statuses.
What to Do Next: Poll Search File Batch Upload Results (primary, per-file progress). Get an Activity Log is optional for high-level batch activity only — do not use it instead of Search for file-level success/failure.
Minimal Request Example:
{
"DeviceInfos": [
{
"device_id": "fa6edcff65ab444e8b5e0eb08df4175d",
"device_name": "Air 1"
}
],
"Bucket": "media-prod",
"LocalDir": "/sdcard/AirDroid/videos",
"FileNamePattern": ".*\\.(mp4|pdf|jpg)$",
"UploadHost": "https://up-z2.qiniup.com",
"Timezone": "UTC"
}
Minimal Response Example:
{
"OperationLogId": "1770854462319857000",
"Hint": "",
"Retryable": false,
"OriginalStatusCode": 200,
"StatusCode": 200,
"ErrorMessage": ""
}
Recipes (Common Recipes)
Recipe 1: Two Devices, Default Overwrite
When to use: Standard batch upload; Overwrite is true (default) — existing object keys are overwritten; DedupDays does not apply.
{
"DeviceInfos": [
{ "device_id": "fa6edcff65ab444e8b5e0eb08df4175d", "device_name": "Air 1" },
{ "device_id": "a286bea023eb4bfc8ef04770ee7dbb5e", "device_name": "Warehouse Pad" }
],
"Bucket": "media-prod",
"LocalDir": "/sdcard/AirDroid/videos",
"FileNamePattern": ".*\\.(mp4|pdf|jpg)$",
"UploadHost": "https://up-z2.qiniup.com",
"Timezone": "Asia/Shanghai",
"Overwrite": true,
"WifiOnly": false
}
Object key prefix on device: {device_name}/{YYYY-MM-DD}/ (date uses Timezone; / in device_name becomes _ in the prefix).
Recipe 1b: Dedup Window (Overwrite Off)
When to use: Skip uploads when the same key succeeded within the dedup window.
{
"DeviceInfos": [
{ "device_id": "fa6edcff65ab444e8b5e0eb08df4175d", "device_name": "Air 1" }
],
"Bucket": "media-prod",
"LocalDir": "/sdcard/AirDroid/videos",
"FileNamePattern": ".*\\.(mp4|pdf|jpg)$",
"UploadHost": "https://up-z2.qiniup.com",
"Overwrite": false,
"DedupDays": 7
}
Recipe 2: Poll Until Success
When to use: After a successful upload call returns OperationLogId.
Input is for Search File Batch Upload Results (not this tool):
{
"OperationLogId": "1770854462319857000",
"PageIndex": 1,
"PageSize": 100,
"Filter": { "status": { "eq": "success" } }
}
Poll until no rows remain in pending / uploading, or inspect failed rows. Stop when all targeted files reach terminal status or your workflow timeout.
Recipe 3: Retry Failed Uploads
When to use: Some devices/files show status: failed in search results.
Use Retry Batch Qiniu File Upload with the same Bucket and original OperationLogId, then poll RetryOperationLogId via Search File Batch Upload Results.
{
"OperationLogId": 1770854462319857000,
"Bucket": "media-prod"
}
1. Overview
1.1 Description
Generates resumable Qiniu upload configuration per device and pushes a batch upload task to selected Android devices. Windows targets are not supported for this file batch path.
Before calling the AirDroid API, the tool preflights Qiniu (AccessKey/SecretKey + bucket list). Per-device upload tokens are valid for 3 hours (10800 seconds). Each file is capped at 5 GB (5368709120 bytes) in upload policy.
1.2 When to Use
- Collect logs, media, or documents from many devices into a Qiniu bucket
- Scheduled or workflow-driven off-device backup
1.3 Execution Mode and Response
Asynchronous at device level. The HTTP call returns immediately with OperationLogId when accepted. Per-file progress is in Search File Batch Upload Results.
Devices should be online to receive the task promptly.
1.4 Prerequisites
| Condition | Description | How to check |
|---|---|---|
| Batch Upload Files feature | Standard/Enterprise/Trial (not Basic) | Hint on plan-related failures |
| Workbench Batch Upload Files permission | Read-write for this action | Admin Console roles |
| Qiniu credential | Valid AccessKey/SecretKey on the node | Preflight or -1 preflight errors |
| Android DeviceInfos | Up to 100 entries from List/Search | List Devices / Search Devices |
1.5 Prerequisite Tools
| Tool | Purpose | Required? |
|---|---|---|
| List Devices / Search Devices | Build DeviceInfos with device_id and device_name | Yes |
1.6 Similar Tools
| Tool | Use instead when |
|---|---|
| Batch Send Files | Pushing files to devices, not uploading from devices |
| Batch Upload S3 Files | S3 instead of Qiniu |
2. Inputs
2.1 Parameter List
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| DeviceInfos | object-array | Yes | — | Up to 100 devices; each needs device_id, device_name |
| Bucket | string | Yes | — | Qiniu bucket name |
| LocalDir | string | Yes | — | Directory on device to scan (no subfolders) |
| FileNamePattern | string | Yes | — | Regex on file names only |
| UploadHost | string | Yes | — | Qiniu upload domain URL (https://…) |
| Timezone | string | No | UTC | IANA timezone for date in key prefix |
| Overwrite | bool | No | true | Overwrite existing objects; when true, DedupDays ignored |
| WifiOnly | bool | No | false | Restrict upload to Wi‑Fi when true |
| DedupDays | number | No | 7 | Whole number 1–90; used only when Overwrite is false |
2.2 Credentials (two groups on the workflow node)
| Credential group | Fields | Purpose |
|---|---|---|
| AirDroid Business OAuth2 | Access token (and related OAuth fields on the node) | Calls batchuploadfiles |
| Qiniu | AccessKey, SecretKey | Bucket preflight + per-device upload token signing |
Missing AirDroid token → -1, access_token is invalid. Missing Qiniu keys → -1, AccessKey is required. / SecretKey is required. Invalid Qiniu AK/SK or bucket → preflight -1 or 500 with Qiniu preflight ErrorMessage (see §5.2).
2.3 Parameter Details
`DeviceInfos`
- Format: [{"device_id":"...","device_name":"..."}]
- Max: 100 devices per call; no duplicate device_id
- Source: List Devices / Search Devices — use the same device_name as returned (drives object key prefix)
- Fill in a GI node: Paste JSON array constant, or map upstream list fields into device_id / device_name pairs
`LocalDir`
- Path on the device (not cloud path)
- Only files directly in this directory are scanned; subdirectories are not included
`FileNamePattern`
- Regex applied to file names only, not full paths
- Escape backslashes in JSON (for example ".*\\.(mp4|jpg)$")
`UploadHost`
- Qiniu upload domain, for example https://up-z2.qiniup.com
- Required non-empty string (typically https)
`Timezone`
- IANA name (for example UTC, Asia/Shanghai)
- Invalid name → StatusCode -1, Timezone is invalid: …
- Key prefix: {device_name}/{YYYY-MM-DD}/ with / in device_name replaced by _
`Overwrite` / `DedupDays` / `WifiOnly`
- Overwrite and WifiOnly must be JSON boolean, not "true" strings
- DedupDays must be a JSON integer 1–90 (not 7.0 float); effective only when Overwrite is false
2.4 Parameter Combination Logic
- All listed required fields must be present together.
- Split large fleets into multiple calls (≤100 devices each).
3. Outputs
3.1 Response Examples
Success (batch accepted): See Quick Start.
Validation failure:
{
"OperationLogId": "",
"Hint": "Pass device objects from 'List Devices' or 'Search Devices' with device_id and device_name, then retry.",
"Retryable": false,
"OriginalStatusCode": 0,
"StatusCode": -1,
"ErrorMessage": "DeviceInfos must be a non-empty array."
}
Business rejection (plan, permission, device, etc.):
StatusCode remains 200; OperationLogId stays empty. ErrorMessage is upstream msg (wording not fixed). Follow Hint.
{
"OperationLogId": "",
"Hint": "Batch Upload Files is not included on Basic; upgrade to Standard, Enterprise, or Trial, or ask an administrator.",
"Retryable": false,
"OriginalStatusCode": 200,
"StatusCode": 200,
"ErrorMessage": "<upstream business message>"
}
HTTP failure on batch API (OAuth, etc.):
Still StatusCode 200 with non-empty ErrorMessage (for example HTTP 403: …). Check OriginalStatusCode and Hint — do not assume StatusCode 500.
{
"OperationLogId": "",
"Hint": "Provide a valid AirDroid Business OAuth2 access_token and valid parameters, then retry.",
"Retryable": false,
"OriginalStatusCode": 403,
"StatusCode": 200,
"ErrorMessage": "HTTP 403: ..."
}
Transport / timeout:
{
"OperationLogId": "",
"Hint": "Retry once; if timeout persists, reduce the number of devices and retry.",
"Retryable": true,
"OriginalStatusCode": 200,
"StatusCode": 500,
"ErrorMessage": "Request timeout after 60 seconds."
}
3.2 Field Descriptions
| Field | Type | Description |
|---|---|---|
| OperationLogId | string | Present when batch accepted; poll with Search File Batch Upload Results |
| StatusCode | number | 200 = call finished (check ErrorMessage); -1 = local validation or Qiniu preflight classified as param error; 500 = timeout, network, or selected preflight/unexpected failures |
| ErrorMessage | string | Empty only when batch accepted; non-empty on validation, business rejection, HTTP error text, or transport failure |
| Hint | string | Plan, permission, device, credential, or retry guidance |
| Retryable | bool | Whether repeating the same request may help |
| OriginalStatusCode | number | HTTP status from AirDroid or Qiniu when available; 0 when no usable HTTP response (some preflight/network cases) |
3.3 Status Values in Payload
Not applicable — no per-file rows in this response; use Search File Batch Upload Results after acceptance.
4. Examples
4.1 Too Many Devices
Request: 101 devices in DeviceInfos
Response: StatusCode -1, Maximum 100 devices per request. Split into multiple calls.
4.2 Duplicate device_id
Response: StatusCode -1, DeviceInfos contains duplicate device_id: …
4.3 Qiniu Bucket Not Found (preflight)
Response: Often StatusCode -1, ErrorMessage containing Qiniu bucket '…' was not found (or similar preflight text); fix Bucket or credential scope.
5. Error Handling
5.1 StatusCode Semantics (This Action)
| StatusCode | Meaning | Agent action |
|---|---|---|
| -1 | Local validation, invalid types, or Qiniu preflight treated as fix-params | Fix inputs/credentials; do not retry unchanged |
| 200 | Call finished | Empty ErrorMessage = accepted — poll Search; non-empty = business or HTTP rejection (plan/permission/device/OAuth) — follow Hint, usually no blind retry |
| 500 | Timeout, network, some preflight failures, unexpected errors | Check Retryable; reduce device count on repeated timeout |
Important: Plan, permission, and many OAuth HTTP errors appear as StatusCode 200 + non-empty ErrorMessage, not 500.
5.2 Common Errors
| StatusCode | ErrorMessage (example) | Fix |
|---|---|---|
| -1 | Maximum 100 devices per request. Split into multiple calls. | Split DeviceInfos |
| -1 | DeviceInfos contains duplicate device_id: … | Deduplicate |
| -1 | Timezone is invalid: … | Use valid IANA timezone |
| -1 | DedupDays must be an integer between 1 and 90. | Use integer 1–90, Overwrite: false |
| -1 | Qiniu credential is invalid (HTTP 401). … | Fix Qiniu AK/SK |
| -1 | Qiniu bucket 'xxx' was not found… | Fix bucket name |
| 200 | <upstream msg> + plan Hint | Upgrade plan per Hint |
| 200 | <upstream msg> + permission Hint | Enable Batch Upload Files read-write |
| 200 | HTTP 403: … | Refresh OAuth token / scope |
| 500 | Request timeout after 60 seconds. | Retry if Retryable; shrink batch |
Use ErrorMessage and Hint text for decisions — not internal upstream codes in user-facing logic.
5.3 Agent Self-Healing
| StatusCode | Auto-retry | Notes |
|---|---|---|
| -1 | No | Fix parameters or credentials |
| 200 + ErrorMessage | Usually no | Business/HTTP rejection — read Hint |
| 200 + empty ErrorMessage | No | Poll Search File Batch Upload Results |
| 500 | Maybe | Only when Retryable is true; after timeout, confirm whether a partial batch was accepted before resubmitting all devices |
- After OperationLogId is returned, always poll Search before declaring overall success.
- On partial failure, use Retry Batch Qiniu File Upload — do not blindly re-run full upload for all devices.
- Not idempotent: duplicate full uploads may create duplicate work; see §6.3.
6. Best Practices
6.1 Performance
- Keep DeviceInfos ≤100; paginate fleet uploads.
- Use FileNamePattern to limit bytes uploaded.
6.2 Security
- 🟡 Devices exfiltrate files to your bucket—scope LocalDir and pattern tightly.
- Protect Qiniu keys on the credential node.
6.3 Idempotency
- Not idempotent (Idempotency: No in tool Note).
- A successful accept plus OperationLogId does not mean re-running the same call is safe after timeout — check Search results before submitting again.
- Prefer Retry Batch Qiniu File Upload for failed files instead of repeating full fleet uploads.
6.4 Async tracking
- Accept → save OperationLogId (string).
- Loop Search File Batch Upload Results until statuses are terminal.
- Failures → Retry Batch Qiniu File Upload → poll RetryOperationLogId.
- Optional: Get an Activity Log for coarse batch status only.
7. Related Tools
| Tool | Role |
|---|---|
| Search File Batch Upload Results | Primary — per-file/device status for OperationLogId |
| Retry Batch Qiniu File Upload | Retry failures from a prior batch |
| Get an Activity Log | Optional coarse batch activity (not a substitute for Search) |
8. Tool Chains
8.1 Upload → Poll → Retry
Batch Upload Qiniu Files → Search File Batch Upload Results (loop until terminal statuses) → Retry Batch Qiniu File Upload (if needed) → Search File Batch Upload Results (on RetryOperationLogId)
Appendix Reference:
Leave a Reply.