{ "openapi": "3.0.1", "info": { "title": "Bright Data API", "description": "将 Bright Data API 集成到您的流程中，以实现高端的爬取精度", "version": "1.0.0" }, "servers": [ { "url": "https://api.brightdata.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/cities": { "get": { "description": "获取指定国家的城市列表", "parameters": [ { "in": "query", "name": "country", "description": "2 位 `COUNTRY_CODE`", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "example": { "c_id": "US", "region": "Texas", "r_id": "TX", "country": "United States", "name": "Cherokee" } } } } } } } } }, "/countrieslist": { "get": { "operationId": "listAllAvailableCountriesPerZoneType", "description": "按区域类型列出所有可用国家", "responses": { "200": { "description": "成功请求并返回响应体", "content": { "application/json": { "schema": { "type": "object", "properties": { "zone_types": { "type": "object", "properties": { "DC_shared": { "type": "object", "properties": { "country_codes": { "type": "array", "items": { "type": "string" } } }, "required": ["country_codes"] }, "DC_dedicated_ip": { "type": "object", "properties": { "country_codes": { "type": "array", "items": { "type": "string" } } }, "required": ["country_codes"] }, "DC_dedicated_host": { "type": "object", "properties": { "country_codes": { "type": "array", "items": { "type": "string" } } }, "required": ["country_codes"] }, "ISP_shared": { "type": "object", "properties": { "country_codes": { "type": "array", "items": { "type": "string" } } }, "required": ["country_codes"] }, "ISP_dedicated_ip": { "type": "object", "properties": { "country_codes": { "type": "array", "items": { "type": "string" } } }, "required": ["country_codes"] }, "ISP_dedicated_host": { "type": "object", "properties": { "country_codes": { "type": "array", "items": { "type": "string" } } }, "required": ["country_codes"] } }, "required": [ "DC_shared", "DC_dedicated_ip", "DC_dedicated_host", "ISP_shared", "ISP_dedicated_ip", "ISP_dedicated_host" ] } }, "required": ["data", "zone_types"], "title": "ListAllAvailableCountriesPerZoneTypeOk" } } } } } } }, "/customer/balance": { "get": { "description": "通过 API 获取总余额", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "number", "description": "账户中的金额", "example": 456 }, "pending_balance": { "type": "number", "description": "您在下一个账单周期将被计费的金额", "example": 123 } } } } } } } } }, "/customer/bw": { "get": { "description": "获取所有区域的带宽统计信息", "parameters": [ { "in": "query", "name": "from", "description": "开始时间", "required": false, "schema": { "type": "string" }, "example": "2018-07-01T00:00:00" }, { "in": "query", "name": "to", "description": "结束时间", "required": false, "schema": { "type": "string" }, "example": "2018-07-02T00:00:00" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ID": { "customer_id": "CUST_ID", "from": "2022-10-01T00:00:00.000Z", "to": "2022-11-24T00:00:00.000Z", "data": { "data_center": {}, "isp": {}, "residential": {}, "mobile": {}, "unlocker": {}, "v__ub_browser": {}, "serp": {}, "dc_elastic": {}, "isp1": {}, "test_zone": {}, "test_zone2": {}, "japan": {}, "zone1_res_ex": {}, "zone5_isp": {}, "zone1": {}, "zone2": {}, "zum_rails_res_canada": {}, "zone3": {}, "elastic_log_test": {}, "google_async": {}, "last_value_ts": "2022-11-23T13:41:20.099Z", "last_update_ts": "2022-11-23T14:05:55.108Z", "sums": {} } } } } } } } } } }, "/network_status/{NETWORK_TYPE}": { "get": { "parameters": [ { "in": "path", "name": "NETWORK_TYPE", "description": "可选值: \n\n `all`: 所有网络类型 \n\n `res`: Residential \n\n `dc`: 数据中心 \n\n `mobile`: 移动网络", "required": true, "schema": { "type": "string", "enum": ["all", "res", "dc", "mobile"] } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "status": true } } } } } } } }, "/status": { "get": { "description": "获取账户状态", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStatus" } } } }, "401": { "description": "不支持的认证方式" } } }, "put": { "description": "更新账户状态", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`suspend_manual`: 手动暂停\n\n`active`: 激活", "enum": ["suspend_manual", "active"] } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "suspend_manual" } } } } } } } } }, "/zone": { "post": { "description": "添加新区域", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewZoneBody" } } } }, "responses": { "201": { "description": "区域已添加" } } }, "get": { "description": "获取区域状态", "parameters": [ { "in": "query", "name": "zone", "description": "区域信息", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "created": "2024-10-28T15:58:10.593Z", "password": ["zone-passowrd"], "ips": ["any"], "plan": { "start": "2024-10-31T13:38:23.665Z", "product": "dc", "type": "static", "ip_fallback": 1, "ips_type": "shared", "ips": 120, "bandwidth": "unlimited", "unl_bw_tiers": "std", "auto_cost_override": { "ip_bw": 1, "price_group": "shared" } }, "description": "hash", "perm": "country" } } } } }, "400": { "description": "缺少 zone 参数" } } }, "delete": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "zone": { "type": "string", "description": "可以省略以影响所有区域" } } } } } }, "responses": { "200": { "description": "成功" } } } }, "/zone/blacklist": { "post": { "description": "将 IP 添加到区域的黑名单", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneAndIP" } } } }, "responses": { "201": { "description": "成功" } } }, "get": { "description": "获取特定区域的黑名单 IP 列表", "parameters": [ { "in": "query", "name": "zones", "description": "逗号分隔的区域 ID 列表进行筛选。如果未提供，默认值为 '*'，表示所有区域。", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ZONE1": ["127.0.0.1"], "ZONE2": ["127.0.0.2"] } } } } } } }, "delete": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "zone": { "type": "string", "description": "区域名称。\n\n**注意**：可以省略以影响所有区域" }, "ip": { "type": "string", "description": "可以使用以下格式之一：\n\n+ 删除单个 IP - `ip=\"1.2.1.2\"`\n+ 删除 IP 范围 - `ip=\"1.2.1.2-1.2.1.10\"`\n+ 删除 IP 子网 - `ip=\"10.20.30.40/24\"`\n+ 删除 IP 掩码 - `ip=\"10.20.30.40/255.255.255.0\"`" } } } } } }, "responses": { "200": { "description": "成功" } } } }, "/zone/bw": { "get": { "description": "获取区域的带宽统计信息", "parameters": [ { "in": "query", "name": "zone", "description": "区域名称", "required": true, "schema": { "type": "string" }, "example": "resi-zone-1" }, { "in": "query", "name": "from", "description": "开始时间", "required": false, "schema": { "type": "string" }, "example": "2018-07-01T00:00:00" }, { "in": "query", "name": "to", "description": "结束时间", "required": false, "schema": { "type": "string" }, "example": "2018-07-02T00:00:00" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ID:": { "customer_id": "customer_id", "from": "2022-10-01T00:00:00.000Z", "to": "2022-11-23T00:00:00.000Z", "data": { "static": { "bw_sum": [ 0, 745, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6960, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "bw_dn": [ 0, 525, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5990, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "bw_up": [ 0, 220, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 970, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "http_direct_req": [ 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "bw_sum_dc": [ 0, 745, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6960, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "bw_api": [ 0, 745, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6960, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "https_direct_req": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] } }, "last_value_ts": "2022-11-19T19:08:51.546Z", "last_update_ts": "2022-11-22T11:35:32.122Z", "sums": { "static": { "back_m1": { "bw_sum": 745, "bw_dn": 525, "bw_up": 220, "http_direct_req": 1, "bw_sum_dc": 745, "bw_api": 745, "https_direct_req": 0 }, "back_m0": { "bw_sum": 6960, "bw_dn": 5990, "bw_up": 970, "http_direct_req": 0, "bw_sum_dc": 6960, "bw_api": 6960, "https_direct_req": 1 }, "back_d2": { "bw_sum": 0, "bw_dn": 0, "bw_up": 0, "http_direct_req": 0, "bw_sum_dc": 0, "bw_api": 0, "https_direct_req": 0 }, "back_d1": { "bw_sum": 0, "bw_dn": 0, "bw_up": 0, "http_direct_req": 0, "bw_sum_dc": 0, "bw_api": 0, "https_direct_req": 0 }, "back_d0": { "bw_sum": 0, "bw_dn": 0, "bw_up": 0, "http_direct_req": 0, "bw_sum_dc": 0, "bw_api": 0, "https_direct_req": 0 } } } } } } } } } } } }, "/zone/change_disable": { "post": { "description": "启用或禁用区域", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["zone", "disable"], "properties": { "zone": { "type": "string", "description": "区域名称" }, "disable": { "type": "number", "description": "`0` - 启用区域\n\n`1` - 禁用区域", "enum": [0, 1] } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "plan": { "start": "2019-07-15T18:08:59.269Z", "type": "static", "ips_type": "shared", "ip_alloc_preset": "shared_block", "bandwidth": "payperusage", "disabled": 1 } } } } } } } } }, "/zone/count_available_ips": { "get": { "description": "获取可用 IP 数量", "parameters": [ { "in": "query", "name": "zone", "description": "区域名称", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "plan", "required": false, "schema": { "type": "object", "properties": { "pool_ip_type": { "type": "string", "description": "若想获取 ISP IP 的可用数量，默认值为数据中心对等 IP。", "default": "static_res" }, "ips_type": { "type": "string", "description": "IP 类型\n\n`shared`: 共享\n\n`selective`: 选择性\n\n`dedicated`: 专用" }, "country": { "type": "string", "description": "IP 所在国家" }, "country_city": { "type": "string", "description": "定义 IP 所在城市" }, "city": { "type": "boolean", "description": "与 `country_city` 参数一起使用" }, "domain_whitelist": { "type": "string", "description": "以空格分隔的域名列表\n\n**注意**: curl 请求中空格需 URL 编码：`d1.com%20d2.com`" }, "geo_db": { "type": "object", "description": "启用/禁用 IP 位置数据库", "properties": { "maxmind": { "type": "boolean", "default": true, "description": "使用 MaxMind IP 位置数据库" }, "dbip": { "type": "boolean", "default": true, "description": "使用 DB-IP IP 位置数据库" }, "google": { "type": "boolean", "default": true, "description": "使用 Google IP 位置数据库" }, "ip2location": { "type": "boolean", "default": true, "description": "使用 IP2Location IP 位置数据库" }, "ipcn": { "type": "boolean", "default": true, "description": "使用 ip.cn IP 位置数据库" } } } } } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "count": 1234 } } } } } } } }, "/zone/cost": { "get": { "description": "获取区域总成本和带宽统计信息", "parameters": [ { "in": "query", "name": "zone", "description": "区域名称", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "from", "description": "开始时间", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "to", "description": "结束时间", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ID": { "back_m2": { "bw": 0, "cost": 0 }, "back_m1": { "bw": 36557298, "cost": 0 }, "back_m0": { "bw": 1219004, "cost": 0 }, "back_d2": { "bw": 82190, "cost": 0 }, "back_d1": { "bw": 0, "cost": 0 }, "back_d0": { "bw": 0, "cost": 0 } } } } } } } } } }, "/zone/domain_perm": { "post": { "description": "向区域允许列表或拒绝列表添加域名", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneAndDomain" } } } }, "responses": { "201": { "description": "成功" } } }, "delete": { "description": "从区域允许列表或拒绝列表删除域名", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["zone", "type", "domain"], "properties": { "zone": { "type": "string", "description": "区域名称" }, "type": { "type": "string", "description": "`whitelist` - 允许列表\n\n`blacklist` - 拒绝列表", "enum": ["whitelist", "blacklist"] }, "domain": { "type": "string", "description": "以空格分隔的域名列表", "example": "d1.com d2.com" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "whitelist": "example.org" } } } } } } } }, "/zone/get_active_zones": { "get": { "description": "获取所有激活的区域", "responses": { "200": { "description": "区域响应", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Zone" } } } } }, "401": { "description": "未找到客户" } } } }, "/zone/ips": { "post": { "description": "为数据中心和 ISP 添加静态 IP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customer", "zone", "count"], "properties": { "customer": { "type": "string", "description": "客户名称" }, "zone": { "type": "string", "description": "区域名称" }, "count": { "type": "number", "description": "IP 数量" }, "country": { "type": "string", "description": "新 IP 的国家，例如 `us`", "example": "us" }, "country_city": { "type": "string", "description": "新 IP 的城市，例如 `us-chicago`", "example": "us-chicago" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "example": ["1.1.1.1", "1.1.1.2", "1.1.1.3"] }, "new_ips": { "type": "array", "items": { "type": "string" }, "example": ["1.1.1.1", "1.1.1.3"] } } } } } } } }, "get": { "description": "获取区域静态 IP（数据中心/ISP）", "parameters": [ { "in": "query", "name": "zone", "description": "区域名称", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "ip_per_country", "description": "获取每个国家的 IP 总数", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ips": [ { "ip": "1.1.1.1", "maxmind": "au", "ext": { "dbip": "au", "ip2location": "au", "google": "us" } }, { "ip": "1.1.1.1", "maxmind": "au", "ext": { "dbip": "au", "ip2location": "au", "google": "us" } } ] } } } } } } }, "delete": { "description": "删除区域的静态 IP", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "zone": { "type": "string", "description": "区域名称", "example": "zone1" }, "ips": { "type": "array", "items": { "type": "string" }, "description": "要删除的 IP 列表", "example": ["1.2.1.2", "1.1.2.2"] } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ips": ["ip1", "ip2"] } } } } } } } }, "/zone/ips/migrate": { "post": { "description": "在区域之间迁移静态 IP（数据中心/ISP）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["from", "to", "ips"], "properties": { "from": { "type": "string", "description": "IP 将从该区域迁出", "example": "zone1" }, "to": { "type": "string", "description": "IP 将迁入的区域", "example": "zone2" }, "ips": { "type": "array", "description": "要迁移的 IP 列表", "example": ["1.1.1.1", "2.1.1.5", "3.1.1.100"] } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "from": "zone1", "to": "zone2", "count": 3 } } } } } } } }, "/zone/ips/refresh": { "post": { "description": "刷新区域的静态 IP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["zone"], "properties": { "zone": { "type": "string", "description": "区域名称", "example": "zone1" }, "vips": { "type": "array", "description": "要刷新的 VIP \n\n **注意**：若需刷新所有已分配的 IP，请省略 `vips` 参数。\n\n **注意**：仅适用于专用住宅 IP", "items": { "type": "string" }, "example": ["vip1", "vip2"] }, "ips": { "type": "array", "description": "要刷新的 IP \n\n **注意**：若需刷新所有已分配的 IP，请省略 `ips` 参数", "items": { "type": "string" }, "example": ["ip1", "ip2"] }, "country": { "type": "string", "description": "新 IP 的国家（例如 `us`）" }, "country_city": { "type": "string", "description": "新 IP 的城市（例如 `us-chicago`）" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "vips": [ { "vip": "tr_9121_07_antalya_10", "country": "tr" }, { "vip": "tr_9121_07_antalya_17", "country": "tr" } ] } } } } } } } }, "/zone/ips/unavailable": { "get": { "description": "获取区域及其静态 IP 的实时状态，显示有连通性问题的 IP", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "zone1": ["1.1.1.1", "100.1.1.2"], "zone10": ["2.1.1.1"] } } } } } } } }, "/zone/passwords": { "get": { "description": "获取区域密码", "parameters": [ { "in": "query", "name": "zone", "description": "区域信息", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功" } } } }, "/zone/permissions": { "get": { "description": "获取区域权限", "parameters": [ { "in": "query", "name": "zone", "description": "区域信息", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功" } } } }, "/zone/proxies_pending_replacement": { "get": { "description": "获取指定区域中所有待替换的代理列表", "tags": ["Proxy"], "parameters": [ { "name": "zone", "in": "query", "description": "区域", "schema": { "type": "string" } } ], "responses": { "200": { "description": "每个区域待替换 IP 的 JSON 列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "ZoneName": { "type": "object", "properties": { "type": { "type": "string", "example": "zone1" }, "ips_to_replace": { "type": "integer", "example": 1 }, "ips_list": { "type": "array", "items": { "type": "object", "properties": { "due_date": { "type": "string", "format": "date" }, "ips": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string", "format": "ipv4" }, "country": { "type": "string" } } } } } } } } } } } } } } } } }, "/zone/recent_ips": { "get": { "description": "获取尝试访问任一指定区域的最近 IP", "parameters": [ { "in": "query", "name": "zones", "description": "获取任一区域尝试访问的 IP: `zones=*`", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ZONE": ["255.0.0.127", "10.0.0.1"] } } } } } } } }, "/zone/route_ips": { "get": { "description": "获取每个区域可用的数据中心/ISP IP", "tags": ["Proxy"], "parameters": [ { "name": "zone", "in": "query", "description": "区域", "required": true, "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "2 字母国家代码", "schema": { "type": "string" } }, { "name": "list_countries", "in": "query", "description": "返回 `[{ip, country},..]` JSON 数组而非纯 IP 列表", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "当 `list_countries=true` 时，返回 JSON 数组；否则返回以换行分隔的 IP 列表", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "当 `list_countries=true` 时，返回 JSON 数组", "properties": { "ip": { "type": "string", "description": "IP 地址", "example": "1.1.1.1" }, "country": { "type": "string", "description": "2 字母国家代码", "example": "us" } }, "example": [ { "ip": "10.0.0.0", "country": "us" }, { "ip": "1.1.1.1", "country": "gb" }, { "ip": "1.1.2.2", "country": "hk" } ] }, { "type": "string", "description": "当 `list_countries=false` 时，IP 将以换行符分隔的纯列表 \n\n ## 示例： \n\n ```\n1.1.1.1\n1.1.2.2\n10.0.0.0\n```", "example": "10.0.0.0/24" } ] } } } } } } }, "/zone/route_vips": { "get": { "description": "获取每个区域所有可用的专用住宅 IP", "parameters": [ { "in": "query", "name": "zone", "description": "区域信息", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功" }, "403": { "description": "未找到 VIP 路由" }, "422": { "description": "所选区域不支持此接口。请仅在具有已分配 gIPs 的活跃专用住宅区域中使用" } } } }, "/zone/static/cities": { "get": { "description": "获取每个国家静态网络可用城市列表", "parameters": [ { "in": "query", "name": "country", "description": "国家", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "pool_ip_type", "description": "网络类型: \n\n `dc`: 数据中心, \n\n `static_res`: ISP", "required": false, "schema": { "type": "string", "default": "dc", "enum": ["dc", "static_res"] } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "example": ["us-chicago", "us-ashburn", "us-siouxfalls"] } } } } } } }, "/zone/status": { "get": { "description": "获取区域状态", "parameters": [ { "in": "query", "name": "zone", "description": "区域信息", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功" } } } }, "/zone/switch_100uptime": { "post": { "description": "切换静态区域自动故障转移开/关", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneAndActive" } } } }, "responses": { "200": { "description": "成功" } } } }, "/zone/vips": { "delete": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["zone", "gips"], "properties": { "zone": { "type": "string", "description": "区域名称" }, "gips": { "type": "array", "items": { "type": "string" }, "description": "要移除的 IP" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" }, "example": ["us_209_wa_seattle_0", "us_7922_ca_fresno_0"] } } } } } } }, "/zone/whitelist": { "post": { "description": "将 IP 添加到区域白名单", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneAndIP" } } } }, "responses": { "201": { "description": "成功" } } }, "get": { "description": "获取指定区域的白名单 IP 列表", "parameters": [ { "in": "query", "name": "zones", "description": "用逗号分隔的区域标识符列表以过滤请求。若未提供，默认为 '*', 表示所有区域", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "example": { "ZONE1": ["127.0.0.1"], "ZONE2": ["127.0.0.2"] } } } } } } }, "delete": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "zone": { "type": "string", "description": "区域名称。 \n\n **注意**: 可省略以影响所有区域。" }, "ip": { "type": "string", "description": "可使用以下格式之一: \n\n + 删除单个 IP - `ip=\"1.2.1.2\"` \n + 删除 IP 范围 - `ip=\"1.2.1.2-1.2.1.10\"` \n + 删除 IP 子网 - `ip=\"10.20.30.40/24\"` \n + 删除 IP 掩码 - `ip=\"10.20.30.40/255.255.255.0\"`" } } } } } }, "responses": { "200": { "description": "成功" } } } } }, "components": { "schemas": { "AccountStatus": { "type": "object", "properties": { "status": { "type": "string" }, "customer": { "type": "string" }, "can_make_requests": { "type": "boolean" }, "auth_fail_reason": { "type": "string" }, "ip": { "type": "string" } }, "example": { "status": "active", "customer": "customer-id", "can_make_requests": false, "auth_fail_reason": "zone_not_found", "ip": "x.x.x.x" } }, "Zone": { "required": ["name"], "type": "object", "properties": { "name": { "description": "区域的名称", "type": "string" }, "type": { "description": "区域类型，例如 serp、isp、mobile 等", "type": "string" } }, "example": { "name": "zone-name", "type": "serp" } }, "Plan": { "required": ["type"], "type": "object", "properties": { "type": { "description": "区域类型", "type": "string", "enum": ["static", "resident", "unblocker", "browser_api"] }, "domain_whitelist": { "description": "允许列表域名的空格分隔列表", "type": "string" }, "ips_type": { "description": "`domain_whitelist` 为 `selective` 时必须提供", "type": "string", "enum": ["shared", "dedicated", "selective"] }, "bandwidth": { "description": "`bandwidth`: 对于 `unlimited`，启用无限带宽", "type": "string", "enum": ["bandwidth", "unlimited"] }, "ip_alloc_preset": { "description": "设置为共享 - 按使用付费类型的区域", "type": "string", "enum": ["shared_block", "shared_res_block"] }, "ips": { "description": "分配给该区域的静态 IP 数量", "type": "integer", "default": 0 }, "country": { "description": "指定要分配给区域的国家 IP，当 `ips_type=static` 时使用", "type": "string", "default": "any" }, "country_city": { "description": "国家代码加城市 (例如 “se-stockholm”) - 指定分配给区域的城市 IP，当 `ips_type=static` 时使用", "type": "string", "default": "any" }, "mobile": { "description": "添加移动代理区域时为 `true`，类型必须为 `resident`", "type": "boolean", "default": "false" }, "serp": { "description": "添加 SERP API 区域时为 `true`", "type": "boolean", "default": "false" }, "city": { "description": "启用城市定位权限时为 `true`", "type": "boolean", "default": "false" }, "asn": { "description": "启用 ASN 定位权限时为 `true`", "type": "boolean", "default": "false" }, "vip": { "description": "分配 `gIP`（IP 组）时为 `true`", "type": "boolean", "default": "false" }, "vips_type": { "description": "添加 Residential 或 Mobile 区域时指定此参数", "type": "string", "enum": ["shared", "domain"] }, "vips": { "description": "分配给区域的 `gIP`（IP 组）数量", "type": "integer", "default": "0" }, "vip_country": { "description": "指定分配给区域的国家 IP，当 `ips_type=resident` 且 `vip=true` 时使用", "type": "string" }, "vip_country_city": { "description": "国家代码加城市 (例如 “se-stockholm”) - 指定分配给区域的城市 IP，当 `ips_type=resident` 且 `vip=true` 时使用", "type": "string", "default": "any" }, "pool_ip_type": { "description": "当 `pool_ip_type` 设置为 `static_res` 时，区域将使用 ISP IP 而非数据中心 IP。", "type": "string" }, "ub_premium": { "description": "设置为 `true` 时可访问高级域名", "type": "boolean", "default": false }, "solve_captcha_disable": { "description": "设置为 `true` 时将禁用验证码解决功能", "type": "boolean", "default": true }, "custom_headers": { "description": "设置为 `true` 时，允许用户在请求中包含自定义头", "type": "boolean", "default": false } } }, "NewZoneBody": { "required": ["zone", "plan"], "type": "object", "properties": { "zone": { "$ref": "#/components/schemas/Zone" }, "plan": { "$ref": "#/components/schemas/Plan" } } }, "ZoneAndIP": { "required": ["ip"], "type": "object", "properties": { "zone": { "description": "区域名称，可省略以影响所有区域", "type": "string" }, "ip": { "description": "`string` 或 `array of strings` \n\n 单个 IP、IP 数组、IP 范围、IP 子网或 IP 掩码 \n\n ### 示例 \n\n - 单个 IP: 10.20.30.40 \n\n - IP 数组: [\"10.20.30.40\", \"50.60.70.80\",...] \n\n - 范围: 10.20.30.40-10.20.30.50 \n\n - 子网: 10.20.30.0/24 \n\n - 子网掩码: 10.20.30.0/255.255.252.0 \n\n **注意** IP 数组语法要求数组中每个 IP 字符串使用引号 `\"`", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "ZoneAndActive": { "required": ["ip"], "type": "object", "properties": { "zone": { "description": "区域名称", "type": "string" }, "active": { "description": "`0`: 禁用自动切换，`1`: 启用自动切换", "type": "integer", "enum": [0, 1] } } }, "ZoneAndDomain": { "required": ["zone", "type"], "type": "object", "properties": { "zone": { "description": "区域名称", "type": "string" }, "type": { "description": "`whitelist` 为允许列表域名，`blacklist` 为拒绝列表域名", "type": "string", "enum": ["whitelist", "blacklist"] }, "domain": { "description": "空格分隔的域名列表", "type": "string" } } }, "Error": { "required": ["error", "message"], "type": "object", "properties": { "error": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。\n\n**认证方法:**\n1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users\n2. 在请求的 Authorization 头中包含 API Key\n3. 格式: `Authorization: Bearer YOUR_API_KEY`\n\n**示例:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df\n```\n\n了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key？", "bearerFormat": "API Key" } } } }