# E-commerce Product Data Collector (`meandering_glow/my-actors`) Actor

Collect product data from supported URLs through an authenticated API. Supports single runs and Standby requests. No additional Actor fee; platform usage costs apply.

- **URL**: https://apify.com/meandering_glow/my-actors.md
- **Developed by:** [arowa](https://apify.com/meandering_glow) (community)
- **Categories:** E-commerce, Automation
- **Features:** Limited permissions, Single-tenant, Server interface
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## E-commerce Product Data Collector

通过认证的上游采集 API 获取商品数据。支持 Apify 普通单次运行与 Standby `POST /collect`，无需浏览器或代理。每次成功请求写入一行 Dataset，完整上游 JSON 放在 `response` 字段；不拆分数组、不猜测商品字段。

### 输入

```json
{
  "mode": "complement",
  "provider": "001",
  "targetFields": ["category_id"],
  "url": "https://item.taobao.com/item.htm?id=123456789"
}
```

示例 URL 仅展示格式，不保证商品存在；请替换为供应商可采集的有效商品。

| 字段 | 类型 | 必填 / 默认 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 必填 | 商品的完整 HTTP(S) 链接 |
| `mode` | string | `complement` | 上游采集模式，原样转发 |
| `provider` | string | `001` | 供应商编号；保持字符串以保留前导零 |
| `targetFields` | string\[] | `["category_id"]` | 请求补充的字段，原样转发 |

Actor 不向上游转发其他输入字段。其他模式、供应商编号和字段的可用范围由上游决定。

### 管理员环境变量

在 Apify Console 的 Actor 环境变量设置中配置，不放入用户输入或公开源码：

| 环境变量 | 设置 |
| --- | --- |
| `UPSTREAM_BASE_URL` | 必填，上游 POST 接口的完整 URL |
| `UPSTREAM_API_KEY` | 必填，原始 Token，不包含 `Bearer ` 前缀；标记为 Secret |
| `UPSTREAM_TIMEOUT_SECONDS` | 可选，正数，默认 `60` 秒 |

请求使用 `Authorization: Bearer <token>` 和 JSON body。不会跟随重定向或自动重试，避免凭据转发和重复采集。生产环境使用 HTTPS。API Token 不应提交 Git，泄露后应撤销并更换。

### 输出

Dataset 的每行包含以下五个字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `url` | string | 本次商品 URL |
| `mode` | string | 本次模式 |
| `provider` | string | 本次供应商 |
| `targetFields` | string\[] | 本次请求字段 |
| `response` | object 或 array | 上游完整 JSON，内部字段取决于供应商 |

可从 Apify Dataset 导出 JSON、CSV 或 Excel；嵌套的 `response` 建议使用 JSON 导出。

默认 Key-value store 的 `STATE` 保存 `status` 和 `resultCount`。`resultCount` 为当前进程已写入的成功请求数，不是历史 Dataset 总行数。运行中止时先保存 `aborted` 状态，再退出。

HTTP 错误、连接错误、超时、非 JSON 或标量 JSON 会使普通运行失败；Standby 返回 502。已观察到的上游业务失败（整数 `code >= 400` 或 `data.status == "failed"`）同样不会写入 Dataset。错误响应仅包含安全摘要，不回显上游原始 body 或 Token。对于其他上游业务状态，不承诺商品有效性。

### Standby 接口

保留 `usesStandbyMode: true`。仅当 `APIFY_META_ORIGIN=STANDBY` 时启动 HTTP 服务；普通 Console/API 运行读取 Actor 输入，采集一次后退出。

- `GET /`：返回 `{"status":"ready","endpoint":"POST /collect"}`。带 `x-apify-container-server-readiness-probe` 时返回 HTTP 200 和 `{"status":"ok"}`，不触发采集。
- `POST /collect`：`Content-Type: application/json`，body 与上述输入一致；成功返回 Dataset 行并存储。400 表示输入无效，415 表示媒体类型错误，502 表示上游失败，500 表示内部或存储错误。
- 未定义路径返回 404。

从 Console 的 **Endpoints** 页复制实际 Standby URL。调用该 URL 使用 **Apify API Token**，不是管理员的上游 Token；上游认证由 Actor 内部处理。服务串行处理请求，不进行批量或并发采集。

### 本地运行

```powershell
uv venv .venv
uv pip install --python .venv/Scripts/python.exe -r requirements.txt
npm install -g apify-cli
.\.venv\Scripts\Activate.ps1
$env:UPSTREAM_BASE_URL = '<上游接口完整 URL>'
## 从安全渠道设置 UPSTREAM_API_KEY；不要把真实 Token 放入提交文件或命令历史。
apify validate-schema
apify run --no-purge
```

运行前将输入保存到 `storage/key_value_stores/default/INPUT.json`。查看 `storage/datasets/default/` 和 `storage/key_value_stores/default/STATE`。`--no-purge` 保留已有存储；本地 `storage/` 不会同步到 Console。

本地 Standby：设置 `$env:APIFY_META_ORIGIN = 'STANDBY'` 后执行相同的 `apify run --no-purge`，使用日志中的端口调用本地接口。返回普通运行前移除该变量。

### 验证记录

- `apify validate-schema` 已通过 input、Dataset 和 Key-value store schemas；该命令不校验 output 或 OpenAPI schema。
- 本地 `apify run` 已调用真实上游。示例商品返回 HTTP 200 包装的业务错误 `code: 502` / `status: failed`；修正后 Actor 退出码为 1，本次成功计数为 0，没有新增 Dataset 行。
- 成功写入与 Standby 200/400/404/415 路径使用本地受控 HTTP 上游验证；它们不代表真实商品采集成功。
- 首次业务判断修正前，本地 default Dataset 留有一条包含上述错误响应的调试记录，未删除用户存储。它不是成功商品结果。
- 真实成功采集需要供应商支持的有效商品链接；部署后的平台输出仍需单独核验。

### 构建与发布

1. 在 Console 确认上述环境变量，尤其 Secret Token；如曾公开分享 Token，先更换。
2. 将代码提交到已关联的 GitHub 仓库，在 Console 点击 **Build**，等待成功。本地未执行 git push 或 apify push。
3. 使用有效商品 URL 运行，检查状态、Dataset 和 `STATE`。本地验证不能证明平台网络能访问上游；若遇到 Cloudflare 403，需要接口所有者调整访问策略。
4. 在 **Publishing** 完善分类、描述与价格。Standby 收费推荐按官方 [Pay-per-event 文档](https://docs.apify.com/actors/publishing/monetize/pay-per-event)配置；本仓库尚未接入收费事件，不会自动向用户收取自定义事件费。
5. 确认数据授权、接口成本及收款要求后再公开。默认内存为 256 MB，平台运行仍会产生用量费用，不保证免费。

参考：[Standby 开发](https://docs.apify.com/actors/development/programming-interface/standby)、[Actor 输出 schema](https://docs.apify.com/actors/development/actor-definition/output-schema)、[Dataset schema](https://docs.apify.com/storage/dataset-schema)。

# Actor input Schema

## `url` (type: `string`):

Product page URL to send to the upstream API. Must be an absolute http(s) URL.

## `mode` (type: `string`):

Upstream mode parameter, forwarded unchanged under the name 'mode'.

## `provider` (type: `string`):

Upstream provider parameter, forwarded unchanged under the name 'provider'.

## `targetFields` (type: `array`):

Upstream targetFields parameter, forwarded unchanged. One field name per entry.

## Actor input object example

```json
{
  "url": "https://item.taobao.com/item.htm?id=123456789",
  "mode": "complement",
  "provider": "001",
  "targetFields": [
    "category_id"
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

Items of the default dataset. Each item holds the forwarded request parameters and the raw upstream JSON response.

## `state` (type: `string`):

The STATE record in the default key-value store, holding the run status and the number of results collected so far.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "url": "https://item.taobao.com/item.htm?id=123456789"
};

// Run the Actor and wait for it to finish
const run = await client.actor("meandering_glow/my-actors").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "url": "https://item.taobao.com/item.htm?id=123456789" }

# Run the Actor and wait for it to finish
run = client.actor("meandering_glow/my-actors").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "url": "https://item.taobao.com/item.htm?id=123456789"
}' |
apify call meandering_glow/my-actors --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,meandering_glow/my-actors"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/KLF3BkZX7327pmPpc/builds/4YRvEGjfUxtV0GgbQ/openapi.json
