> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 全球代理對接說明

> Global Rotation Agent 集成指南 - XHuoAPI

本文檔主要介紹 XHuoAPI 全球代理的對接說明，包括申請方法、實用方法等具體內容。

## 申請方法

要使用全球服務，可以首先到「[申請頁面](https://api.xhuoapi.ai/services/87ae4a5a-59d9-4c50-86d4-c0b5d393e5af)」進行申請，首次申請有 1 積分免費額度。

![](https://cdn.xhuoapi.ai/cyzvmz.png)

如果您尚未登錄，則會自動跳轉到登錄頁面，登錄之後繼續申請即可。

## 使用方法

申請完畢之後，可以到「控制台」中查看本人的申請結果，如圖所示：

![](https://cdn.xhuoapi.ai/y9boi5.png)

點擊 「Credentials」，即可查看使用全球代理服務的用戶名及密碼，以冒號分隔，其中用戶名是 8 位，密碼是 32 位，如圖所示：

![](https://cdn.xhuoapi.ai/ixwm85.png)

本代理是一種輪換代理（Rotating Proxy），因此使用的時候只需要設置一個固定的代理地址和端口即可，代理的地址和端口分別是 `global.proxy.xhuoapi.ai` 和 `30007`，本代理是 HTTP/HTTPS/SOCKS 協議的代理，可以用於請求 HTTP 和 HTTPS 協議的網站。

> 注意：本代理只能在中國境外網絡環境下使用，中國大陸地區無法使用。

## 命令測試

有了代理的用戶名密碼之後，最方便的方法便是通過 curl 命令行進行測試，如尚未安裝，請參考 [https://curl.se/](https://curl.se/) 安裝即可。

假如當前代理的用戶名密碼是 `1f78266a:eff0896726224fa2a99fe82dd1f07562`，我們可以用如下 curl 命令進行測試：

```shell theme={null}
curl -x 1f78266a:eff0896726224fa2a99fe82dd1f07562@global.proxy.xhuoapi.ai:30007 https://ipinfo.io
```

這裡我們使用 curl 的 `-x` 參數指定了代理地址，代理協議默認是 HTTP/HTTPS，這裡請求的 URL 是 [https://ipinfo.io](https://ipinfo.io)，這個站點可以返回請求該站點的真實 IP 地址和 IP 所在地域。

> 注意：上述用戶名密碼可能無效，請自行替換成你的用戶名密碼。

運行結果如下：

```json theme={null}
{
  "ip": "66.206.249.77",
  "hostname": "host-66-206-249-77.public.eastlink.ca",
  "city": "Kirkland Lake",
  "region": "Ontario",
  "country": "CA",
  "loc": "48.1446,-80.0377",
  "org": "AS11260 EastLink",
  "postal": "P2N",
  "timezone": "America/Toronto",
  "readme": "https://ipinfo.io/missingauth"
}
```

可以看到，返回結果的 country 是 CA，代表加拿大。如果再次運行，可以得到不一樣的結果，每次請求都是隨機的 IP 出口。

## 代碼對接

下面以 Python 為例演示該代理的設置方法：

```python theme={null}
import requests

proxy = 'http://{proxy_username}:{proxy_password}@global.proxy.xhuoapi.ai:30007'

proxies = {
    'http': proxy,
    'https': proxy
}

for _ in range(3):
    resp = requests.get('https://ipinfo.io', proxies=proxies)
    print(resp.text)
```

這裡我們首先聲明了代理的 URL 並定義為 proxy 變量，協議是 http 協議，後面跟隨隧道代理的用戶名和密碼（即控制台展示的用戶名和密碼，二者以冒號分隔），後面再跟一個 `@` 符號，再跟代理的地址和端口即可。

> 注意：您需要將上述代碼中的 `{proxy_username}:{proxy_password}`替換為您的代理用戶名密碼，最終結果類似 `proxy = 'http://1f78266a:eff0896726224fa2a99fe82dd1f07562@global.proxy.xhuoapi.ai:30007'`，注意沒有 `{` 和 `}` 字符。

接著聲明了一個 proxies 變量，配置了兩個鍵值對，鍵名分別為 http 和 https，其鍵值都是 proxy，代表對於 HTTP 和 HTTPS 協議的網站，都是用 proxy 變量定義的代理來進行請求。接下來定義了三次循環進行代理的測試。

運行結果如下：

```python theme={null}
{
  "ip": "103.190.205.165",
  "hostname": "assigned-for-client.adnsl.com",
  "city": "Paltan",
  "region": "Dhaka Division",
  "country": "BD",
  "loc": "23.7362,90.4143",
  "org": "AS38203 ADN Telecom Ltd.",
  "postal": "1000",
  "timezone": "Asia/Dhaka",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "74.111.25.181",
  "hostname": "pool-74-111-25-181.syrcny.fios.verizon.net",
  "city": "Syracuse",
  "region": "New York",
  "country": "US",
  "loc": "43.0481,-76.1474",
  "org": "AS701 Verizon Business",
  "postal": "13201",
  "timezone": "America/New_York",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "207.113.168.248",
  "city": "LaPorte",
  "region": "Indiana",
  "country": "US",
  "loc": "41.6106,-86.7225",
  "org": "AS13428 Surf Air Wireless, LLC",
  "postal": "46350",
  "timezone": "America/Chicago",
  "readme": "https://ipinfo.io/missingauth"
}
```

可以看到，每次運行的結果得到的代理 IP 都是隨機的，而且 IP 所在地域確實是來源於全球不同國家不同城市。

當然，上述的代理設置方式實際上是一個相對簡潔的設置方式。

實際上上述代碼等價於在請求的時候設置了一個額外的 Headers - Proxy Authorization，所以上述代碼還可以改寫如下：

```python theme={null}
import requests
import base64

proxy_host = 'global.proxy.xhuoapi.ai'
proxy_port = '30007'
proxy_username = '{proxy_username}' # 8位用戶名
proxy_password = '{proxy_password}' # 32位密碼

credentials = base64.b64encode(
    f'{proxy_username}:{proxy_password}'.encode()).decode()

proxies = {
    'http': f'http://{proxy_host}:{proxy_port}',
    'https': f'http://{proxy_host}:{proxy_port}'
}

headers = {
    'Proxy-Authorization': f'Basic {credentials}'
}

for _ in range(3):
    resp = requests.get('https://ipinfo.io',
                        proxies=proxies, headers=headers)
    print(resp.text)

```

可以看到，這裡我們通過 Proxy-Authorization 這個請求頭額外設置了代理的用戶名和密碼（需要進行 Base64 編碼），這樣的代碼運行效果也是一樣的。

對於其他語言，比如 JavaScript 的 axios，也可以使用類似的設置方式：

```javascript theme={null}
const axios = require("axios");
const base64 = require("base64");

const proxy_host = "global.proxy.xhuoapi.ai";
const proxy_port = "30007";
const proxy_username = "{proxy_username}"; // 8位用户名
const proxy_password = "{proxy_password}"; // 32位密码

const credentials = base64.encode(`${proxy_username}:${proxy_password}`);

const proxies = {
  http: `http://${proxy_host}:${proxy_port}`,
  https: `http://${proxy_host}:${proxy_port}`,
};

const headers = {
  "Proxy-Authorization": `Basic ${credentials}`,
};

for (let i = 0; i < 3; i++) {
  axios
    .get("https://ipinfo.io", { proxies, headers })
    .then((resp) => console.log(resp.data))
    .catch((err) => console.error(err));
}
```

運行效果都是一樣的。

對於其他語言的設置方法，請參考上文自行改寫即可。

## 地區篩選

我們可以通過在 username 裡面添加 region 來進行地區的篩選，例如如果要選擇美國的代理，原來的 username 是 `1f78266a`，則可以把 username 修改為 `1f78266a-region-us`，上述的 curl 就可以改寫如下：

```
curl -x 1f78266a-region-us:eff0896726224fa2a99fe82dd1f07562@global.proxy.xhuoapi.ai:30007 https://ipinfo.io
```

地區列表：

| 國家或地區名稱    | 國家/地區代碼 |
| ---------- | ------- |
| 美國         | us      |
| 香港         | hk      |
| 安道爾        | ad      |
| 阿聯酋        | ae      |
| 阿富汗        | af      |
| 安提瓜和巴布達    | ag      |
| 安圭拉        | ai      |
| 阿爾巴尼亞      | al      |
| 亚美尼亚       | am      |
| 安哥拉        | ao      |
| 南極洲        | aq      |
| 阿根廷        | ar      |
| 美屬薩摩亞      | as      |
| 奧地利        | at      |
| 澳大利亞       | au      |
| 阿魯巴        | aw      |
| 奧蘭群島       | ax      |
| 阿塞拜疆       | az      |
| 波黑         | ba      |
| 巴巴多斯       | bb      |
| 孟加拉        | bd      |
| 比利時        | be      |
| 布基納法索      | bf      |
| 保加利亞       | bg      |
| 巴林         | bh      |
| 布隆迪        | bi      |
| 貝寧         | bj      |
| 聖巴泰勒米島     | bl      |
| 百慕大        | bm      |
| 文萊         | bn      |
| 玻利維亞       | bo      |
| 荷蘭加勒比區     | bq      |
| 巴西         | br      |
| 巴哈馬        | bs      |
| 不丹         | bt      |
| 布韋島        | bv      |
| 博茨瓦納       | bw      |
| 白俄羅斯       | by      |
| 伯利茲        | bz      |
| 加拿大        | ca      |
| 科科斯群島      | cc      |
| 中非         | cf      |
| 瑞士         | ch      |
| 智利         | cl      |
| 喀麥隆        | cm      |
| 哥倫比亞       | co      |
| 哥斯達黎加      | cr      |
| 古巴         | cu      |
| 佛得角        | cv      |
| 聖誕島        | cx      |
| 塞浦路斯       | cy      |
| 捷克         | cz      |
| 德國         | de      |
| 吉布提        | dj      |
| 丹麥         | dk      |
| 多米尼克       | dm      |
| 多米尼加       | do      |
| 阿爾及利亞      | dz      |
| 厄瓜多爾       | ec      |
| 愛沙尼亞       | ee      |
| 埃及         | eg      |
| 西撒哈拉       | eh      |
| 厄立特里亞      | er      |
| 西班牙        | es      |
| 芬蘭         | fi      |
| 斐濟群島       | fj      |
| 密克羅尼西亞聯邦   | fm      |
| 法羅群島       | fo      |
| 法國         | fr      |
| 加蓬         | ga      |
| 格林納達       | gd      |
| 格魯吉亞       | ge      |
| 法屬圭亞那      | gf      |
| 加納         | gh      |
| 直布羅陀       | gi      |
| 格陵蘭        | gl      |
| 幾內亞        | gn      |
| 瓜德羅普       | gp      |
| 赤道幾內亞      | gq      |
| 希臘         | gr      |
| 危地馬拉       | gt      |
| 關島         | gu      |
| 幾內亞比紹      | gw      |
| 圭亞那        | gy      |
| 赫德島和麥克唐納群島 | hm      |
| 洪都拉斯       | hn      |
| 克羅地亞       | hr      |
| 海地         | ht      |
| 匈牙利        | hu      |
| 印尼         | id      |
| 愛爾蘭        | ie      |
| 以色列        | il      |
| 馬恩島        | im      |
| 印度         | in      |
| 英屬印度洋領地    | io      |
| 伊拉克        | iq      |
| 伊朗         | ir      |
| 冰島         | is      |
| 意大利        | it      |
| 泽西島        | je      |
| 牙買加        | jm      |
| 約旦         | jo      |
| 日本         | jp      |
| 柬埔寨        | kh      |
| 基里巴斯       | ki      |
| 科摩羅        | km      |
| 科威特        | kw      |
| 開曼群島       | ky      |
| 黎巴嫩        | lb      |
| 列支敦士登      | li      |
| 斯里蘭卡       | lk      |
| 利比里亞       | lr      |
| 萊索托        | ls      |
| 立陶宛        | lt      |
| 盧森堡        | lu      |
| 拉脫維亞       | lv      |
| 利比亞        | ly      |
| 摩洛哥        | ma      |
| 摩納哥        | mc      |
| 摩爾多瓦       | md      |
| 黑山         | me      |
| 法屬聖馬丁      | mf      |
| 馬達加斯加      | mg      |
| 馬紹爾群島      | mh      |
| 馬其頓        | mk      |
| 馬里         | ml      |
| 緬甸         | mm      |
| 澳門         | mo      |
| 馬提尼克       | mq      |
| 毛里塔尼亞      | mr      |
| 蒙塞拉特島      | ms      |
| 馬耳他        | mt      |
| 馬爾代夫       | mv      |
| 馬拉維        | mw      |
| 墨西哥        | mx      |
| 馬來西亞       | my      |
| 納米比亞       | na      |
| 尼日爾        | ne      |
| 諾福克島       | nf      |
| 尼日利亞       | ng      |
| 尼加拉瓜       | ni      |
| 荷蘭         | nl      |
| 挪威         | no      |
| 尼泊爾        | np      |
| 瑙魯         | nr      |
| 阿曼         | om      |
| 巴拿馬        | pa      |
| 秘魯         | pe      |
| 法屬波利尼西亞    | pf      |
| 巴布亞新幾內亞    | pg      |
| 菲律賓        | ph      |
| 巴基斯坦       | pk      |
| 波蘭         | pl      |
| 皮特凱恩群島     | pn      |
| 波多黎各       | pr      |
| 巴勒斯坦       | ps      |
| 帕勞         | pw      |
| 巴拉圭        | py      |
| 卡塔爾        | qa      |
| 留尼汪        | re      |
| 羅馬尼亞       | ro      |
| 塞爾維亞       | rs      |
| 俄羅斯        | ru      |
| 盧旺達        | rw      |
| 所羅門群島      | sb      |
| 塞舌爾        | sc      |
| 蘇丹         | sd      |
| 瑞典         | se      |
| 新加坡        | sg      |
| 斯洛文尼亞      | si      |
| 斯洛伐克       | sk      |
| 塞拉利昂       | sl      |
| 聖馬力諾       | sm      |
| 塞內加爾       | sn      |
| 索馬里        | so      |
| 蘇里南        | sr      |
| 南蘇丹        | ss      |
| 聖多美和普林西比   | st      |
| 薩爾瓦多       | sv      |
| 敘利亞        | sy      |
| 斯威士蘭       | sz      |
| 特克斯和凱科斯群島  | tc      |
| 乍得         | td      |
| 多哥         | tg      |
| 泰國         | th      |
| 托克勞        | tk      |
| 東帝汶        | tl      |
| 突尼斯        | tn      |
| 湯加         | to      |
| 土耳其        | tr      |
| 圖瓦盧        | tv      |
| 坦桑尼亞       | tz      |
| 烏克蘭        | ua      |
| 烏干達        | ug      |
| 烏拉圭        | uy      |
| 梵蒂岡        | va      |
| 委內瑞拉       | ve      |
| 英屬維爾京群島    | vg      |
| 美屬維爾京群島    | vi      |
| 越南         | vn      |
| 瓦利斯和富圖納    | wf      |
| 薩摩亞        | ws      |
| 也門         | ye      |
| 馬約特        | yt      |
| 南非         | za      |
| 贊比亞        | zm      |
| 津巴布韋       | zw      |
| 剛果（布）      | cg      |
| 剛果（金）      | cd      |
| 莫桑比克       | mz      |
| 根西島        | gg      |
| 冈比亞        | gm      |
| 北馬里亞納群島    | mp      |
| 埃塞俄比亞      | et      |
| 新喀里多尼亞     | nc      |
| 瓦努阿圖       | vu      |
| 法屬南部領地     | tf      |
| 纽埃         | nu      |
| 美國本土外小島嶼   | um      |
| 庫克群島       | ck      |
| 英國         | gb      |
| 特立尼達和多巴哥   | tt      |
| 聖文森特和格林納丁斯 | vc      |
| **###**    | tw      |
| 新西蘭        | nz      |
| 沙特阿拉伯      | sa      |
| 老撾         | la      |
| 朝鮮 北朝鮮     | kp      |
| 韓國 南朝鮮     | kr      |
| 葡萄牙        | pt      |
| 吉爾吉斯斯坦     | kg      |
| 哈薩克斯坦      | kz      |
| 塔吉克斯坦      | tj      |
| 土庫曼斯坦      | tm      |
| 烏茲別克斯坦     | uz      |
| 聖基茨和尼維斯    | kn      |
| 聖皮埃爾和密克隆   | pm      |
| 聖赫勒拿       | sh      |
| 聖盧西亞       | lc      |
| 毛里求斯       | mu      |
| 科特迪瓦       | ci      |
| 肯尼亞        | ke      |
| 蒙古國        | mn      |

## IP 固定

和上述内容一样，我們可以透過在 username 裡面添加 `session` 並添加一個 5 位固定數字，來實現一段時間內的 IP 固定，有效期大約 10 分鐘。

例如如果要實現一段時間內的 IP 固定，原來的 username 是 `1f78266a`，則可以把 username 修改為 `1f78266a-session-12345`，其中的 `12345` 如果不變，那麼一段時間內 IP 就不變，上述的 curl 就可以改寫如下：

```
curl -x 1f78266a-session-12345:eff0896726224fa2a99fe82dd1f07562@global.proxy.xhuoapi.ai:30007 https://ipinfo.io
```

## 購買更多

如您的套餐已經耗尽，您需要購買更多才能繼續使用該代理服務。

要購買更多，請到「[申請頁面](https://api.xhuoapi.ai/services/87ae4a5a-59d9-4c50-86d4-c0b5d393e5af)」直接點擊「購買更多」按鈕即可選購，單次購買更多，單價越便宜。