什么是API

API（应用程序编程接口）是一种编程接口，允许软件系统之间进行通信。可以将其比作餐厅：你下订单，服务员将订单送到厨房，然后将菜品带回来。当你的应用程序通过API发送请求并从Octo Browser服务器接收响应时，也会发生同样的事情。

HTTP请求

API通信是通过HTTP请求进行的——即客户端发送给服务器的消息，用于请求或传输数据。

主要HTTP方法

请求结构

每个请求由几个组件组成：

• URL：请求发送的地址。

• 方法：我们想要执行的操作（GET、POST等）。

• 头信息：额外的请求信息（例如，一个API令牌）。

• 正文：我们发送的数据（例如，新配置文件的信息）。

让我们通过一个POST请求、Node.js和Axios库创建一个配置文件。以下是一个示例脚本：

const axios = require('axios');
const data = JSON.stringify({
  "title": "Test profile from api",
  "fingerprint": {
    "os": "win"
  }
});
const config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://app.octobrowser.net/api/v2/automation/profiles',
  headers: { 
    'Content-Type': 'application/json', 
    'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>'
  },
  data : data
};
axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

URL： 'https://app.octobrowser.net/api/v2/automation/profiles'（用于处理配置文件的API端点）。

方法： 'post'（创建新配置文件）。

请求正文（数据）：一个包含必需字段（配置文件名称和操作系统）的JSON对象。

头信息：

• Content-Type'：'application/json'告诉服务器数据是以JSON格式发送的。

• 'X-Octo-Api-Token': '<GET_TOKEN_IN_CLIENT>'是一个在主帐户设置中可用的唯一API令牌，适用于Base及以上订阅。

在你发送请求后，服务器会始终返回一个包含状态代码的HTTP响应——一个三位数的数字，指示处理请求的结果。

服务器响应

• 成功（2xx）:

{"success":true,"msg":"","data":{"uuid":"<profile_uuid>"},"code":null}

• 错误（4xx和5xx）：
  
  

  • 400 错误请求——语法错误或缺少必要参数。

  • 401 未授权——API令牌无效或缺失。

  • 404 未找到——URL不存在。

  • 429 请求过多——请求限制已超出。

  • 500 内部服务器错误——服务器端错误。

脚本中的 .catch 块帮助处理这些错误。

Octo Browser API 文档

官方Octo Browser API文档包括请求结构和使用示例：

• 左侧菜单列出了诸如Profiles、Proxies、Local Client API、Teams等章节。

• 中心包含请求描述：端点、方法（GET、POST等）、参数、头信息和使用示例。

• 右侧包括现成的请求示例和服务器响应。

• LANGUAGE下拉菜单让你可以选择Node.js、Python、Java、C#、PHP和其他语言的示例。

使用公共和本地API

公共API

• 在线提供的远程接口。无需浏览器运行。

• 请求发送至：https://app.octobrowser.net。

• 限制取决于订阅：

使用公共API，你可以：

• 检索配置信息；

• 创建、编辑和删除配置文件；

• 与标签、团队和代理进行操作。

请求示例：创建一个配置文件

POST https://app.octobrowser.net/api/v2/automation/profiles

Header: X-Octo-Api-Token: <你的_API_令牌>

本地API

• 当Octo Browser在设备上运行时，本地工作。

• 限制取决于请求类型：启动配置文件——1个请求，一次性配置文件——4个请求。所有其他本地API请求不影响限制。

• 你可以登录、启动和停止配置文件，并连接自动化库。

• 请求发送至：http://localhost:58888（58888是本地HTTP服务器的端口）。

请求示例：启动一个配置文件

POST http://localhost:58888/api/profiles/start

Header: Content-Type: application/json 并带有UUID和其他参数的JSON正文。

发送请求的解决方案

Postman

1. 下载Postman或使用网页版。

2. 使用“Run in Postman”按钮将Octo Browser API导入工作区。

3. 选择一个请求（例如，POST创建配置文件→简单配置文件）。

4. 指定https://app.octobrowser.net而不是{{baseUrl}}。

   

5. 在Headers标签中设置API令牌。

   

6. 在Body标签中输入所需的配置文件参数。
   
   

   

7. 单击“发送”以创建一个配置文件。

同样适用于启动配置文件：

1. 选择POST启动配置文件请求。

2. 指定本地API URL：http://localhost:58888。

3. 在“历史和恢复”中找到配置文件UUID，在配置文件表中，或使用GET获取配置文件请求。

4. 在Body标签中设置参数：

• uuid：配置文件ID；

• headless：无GUI启动（true/false）；

• debug_port：启用自动化端口（true/false或指定端口）；

• timeout：超时时间（秒）；

• only_local：限制访问本地主机（true/false）；

• flags：额外参数（例如，["--start-maximized"]）；

• password：如果设置了，配置文件的密码。

5. 单击“发送”并检查响应。

VS Code

1. 下载并安装VS Code。

2. 下载并安装node.js以用于JavaScript。

3. 下载并安装Python以用于Python脚本。

4. 打开VS Code并创建一个项目文件夹。

5. 安装依赖项：

   • 对于Node.js：npm install axios。

   • 对于Python：pip install requests。

6. 复制Octo文档示例，用于使用node.js和axios创建配置文件。

7. 创建一个.js文件并将脚本粘贴进去。

8. 插入你的API令牌并保存文件。

9. 使用命令node <filename>运行脚本（例如，node post_create_profile）。"

同样，使用Python启动配置文件时，在示例请求中选择POST启动配置文件，将脚本粘贴到.py文件中，保存并运行它。

终端/CMD

你也可以在终端/CMD中使用API。为此，在LANGUAGE菜单中选择cURL。

将你的API令牌插入到POST创建配置文件请求中并运行：

重要提示：在Windows上的CMD中，你需要适应语法，因为CMD与类Unix shell的命令解释不同。特别是，必须正确处理引号，并正确处理换行符。以下是一个适应后的启动配置文件脚本示例：

curl --location "http://localhost:58888/api/profiles/start" ^
--header "Content-Type: application/json" ^
--data "{\"uuid\": \"42c4231d71f6495fb33e70d97915c696\", \"headless\": false, \"debug_port\": true, \"timeout\": 120, \"only_local\": true, \"flags\": [], \"password\": \"\"}"

*插入所需配置文件的UUID。

这些并不是使用Octo Browser API的所有可能方式—这只是一些示例。

自动化框架和CDP

CDP（Chrome DevTools Protocol）允许通过代码控制配置文件操作：打开网站、点击、输入和截屏。

Octo Browser支持通过本地API进行CDP连接。当你通过POST启动配置文件启动配置文件时，你需要传递debug_port参数：true（或指定一个端口），Octo会打开一个用于远程访问的端口（例如，ws://127.0.0.1:53215/devtools/browser/...）。

使用CDP端口启动配置文件的示例：

curl --location 'http://localhost:58888/api/profiles/start' \
--header 'Content-Type: application/json' \
--data '{
    "uuid": "eb5d6441b2b349368b31fd901b82a8ac",
    "headless": false,
    "debug_port": true,
    "timeout": 120,
    "only_local": true
}'

响应将包含连接地址：

{"uuid":"eb5d6441b2b349368b31fd901b82a8ac","state":"STARTED","headless":false,"start_time":1761735064,"ws_endpoint":"ws://127.0.0.1:53215/devtools/browser/d633f197-1623-4f61-a9b0-28a65e0df2fd","debug_port":"53215","one_time":false,"browser_pid":57411,"connection_data":{"ip":"","country":""}}

你可以在任何支持CDP的库中使用此地址，例如Puppeteer/Pyppeteer或Playwright。详细的使用示例可以在文档中找到。

除了直接使用CDP外，你还可以通过WebDriver将Selenium连接到Octo Browser配置文件。在这种情况下，Selenium通过debug_port控制已运行的浏览器，但使用WebDriver而不是直接CDP命令。连接示例可在文档中找到。

使用自动化库打开了广泛的可能性，从配置文件预热和收集cookie到构建复杂的账户注册逻辑和管理账户操作。

如何在Docker中运行Octo Browser

Docker是一种用于自动化应用程序在容器中部署和管理的软件。每个容器都有自己的操作系统（通常是Linux）、库、依赖项和设置。但与虚拟机不同，容器轻便且启动速度非常快。

在Docker中使用Octo Browser的好处：

• 隔离：Octo Browser及其依赖项独立运行，不与其他应用程序冲突。

• 便携性：相同的容器可以在服务器、笔记本电脑或VPS上运行，一切都会以同样的方式工作。

• 可扩展性：你可以同时运行许多配置文件，并在需要时创建新容器以处理更多配置文件。

• 自动化：适用于脚本，其中浏览器在无图形界面模式下运行。

运行Docker：

1. 准备一个Dockerfile。Ubuntu 22.04的Dockerfile示例，包括所有依赖项，包括Octo Browser和Google Chrome，可以在文档中找到。

2. 构建一个Docker容器：

docker build -t octobrowser:latest

3. 运行容器：

docker run --name octo -it --rm \
       --security-opt seccomp:unconfined \
       -v '/srv/docker_octo/cache:/home/octo/.Octo Browser/' \
       -p 58895:58888 \
       octobrowser:latest

如何使用Kubernetes管理Octo Browser容器

Kubernetes (K8s)帮助管理多个容器。

• Docker旨在运行单个容器。

• Kubernetes帮助运行整个容器集群，自动负载分配。

你可以使用Minikube、kind、Docker Desktop或其他工具运行Kubernetes。

Octo Browser和Kubernetes的工作流程：

1. 构建Docker容器。

2. 运行容器。

3. 使用Kubernetes管理容器。

Deployment YAML示例可在文档中找到。

有用的脚本和代码片段

在Octo Browser API的文档中，你不仅会找到基本方法，还有Node.js和Python的现成脚本。文档中描述了以下场景：

1. 批量创建配置文件——指定配置文件数量和你的API令牌。

2. 批量向选定配置文件添加扩展、启动页和书签——指定配置文件列表、扩展、启动页、书签和API令牌。

3. 批量向所有配置文件添加扩展、启动页和书签——指定扩展、启动页、书签和API令牌。

4. 批量向具有特定标签的配置文件添加扩展、启动页和书签——指定标签、扩展、启动页、书签和API令牌。

5. 从.txt文件批量创建代理并随后使用这些代理创建配置文件——文件格式必须为protocol;host;port;login;password;title;change_ip_url（change_ip_url是可选的）。在脚本中指定API令牌和文件名。

6. 将保存的代理添加到配置文件——指定代理、配置文件和API令牌。

7. 从浏览器的导出列表中将所有已导出的配置文件复制到指定文件夹——指定文件夹和API令牌。

8. 生成一个包含所有Octo Browser帐号中配置文件名称的.txt文件——插入你的API令牌。

API常见问题

如何通过API在创建配置文件时传递参数？

请求体示例：

const body = {
  title: "profile_title", // required field
  fingerprint: {
    os: "mac", // required field: "mac", "win", or "android"
    os_arch: "arm", // optional field: you can set "x86" if you want to create a mac profile with an Intel processor
    os_version: "13" // optional field
    /*
      Possible values:
      — for Windows: 10, 11
      — for macOS (arm): 12, 13, 14, 15
      — for macOS (x86): 12, 13, 14, 15
      — for Android: 12, 13, 14, 15
    */
  }
};

指纹对象内的os字段是必需的。如果未指定其他参数，Octo Browser将自动生成它们的最佳值。

要查看创建配置文件时可以传递哪些其他参数：

1. 转到Octo Browser API文档 (POST创建配置文件请求)。

2. 向下滚动到Body部分——显示所有可用参数的结构。

3. 创建配置文件后，你可以通过GET获取配置文件请求检索其参数——服务器响应将包含完整的配置文件结构。

一次性配置文件如何工作？

一次性配置文件是一个可丢弃的配置文件，可通过单个API请求创建并立即启动，关闭后自动删除。

• 无需发送单独的请求来创建、启动、停止和删除配置文件。这对于例如网络抓取非常有用，在这种情况下，你只需使用一个新的浏览器指纹访问一个网络资源，收集数据，然后删除配置文件。

• 一次性配置文件在所有具有API访问权限的订阅中可用。

• 一个POST一次性配置文件请求算作你的RPM/RPH限制中的4个请求。

要完成一次性配置文件的工作，你只需发送POST停止配置文件，手动关闭浏览器窗口，或通过Puppeteer、Playwright或类似库以编程方式调用关闭操作——例如，使用await browser.close()。关闭后，配置文件自动删除，不会出现在你的配置文件列表或垃圾箱中。

如果我超过API限制（错误429），该怎么办？

停止你的脚本并暂停一段时间发送请求。你可以在响应头中检查你的API限制：

• Retry-After: 0 # 如果值为零，你可以发送下一个请求

• X-Ratelimit-Limit: 200 # RPM表示每分钟的总请求数

• X-Ratelimit-Limit-Hour: 3000 # RPH表示每小时的总请求数

• X-Ratelimit-Remaining: 4 # 剩余的RPM表示这一分钟内剩余的请求数

• X-Ratelimit-Remaining-Hour: 2999 # 剩余的RPH表示这一小时内剩余的请求数

• X-Ratelimit-Reset: 1671789217 # UNIX时间戳，表示何时重置限制

在耗尽限制时不要发送请求。否则，限制期将增加，可能会施加更严格的速率限制。确保你的脚本在发送请求之前检查这些限制头。

如何获取CDP连接的ws_endpoint？

当你通过API启动配置文件并使用"debug_port": true参数（或指定一个特定端口，例如"debug_port": 20000），Octo Browser在响应中返回一个ws_endpoint值。

此ws_endpoint由自动化库（如Puppeteer或Playwright）用来连接到正在运行的配置文件。

我在哪里可以找到我的API令牌？

API对具有Base订阅及以上的用户开放。

API令牌显示在主帐户设置的“附加”选项卡下。其他团队成员无法查看API令牌。