farmbot开发入门教程-REST API

说明：

• REST API是一个 HTTP Web 服务器，通常称为“API”、“REST API”或简称为“服务器”。REST API 负责处理多项任务，包括：

  • 数据存储、验证和安全：允许用户即使设备处于离线状态也能编辑序列和花园布局等信息，通过将数据存储在云中防止 FarmBot OS 恢复出厂设置之间丢失数据，通过身份验证和授权机制验证数据并控制对数据的访问。
  • 电子邮件传递：向最终用户发送电子邮件通知，例如密码重置和严重错误。所有其他消息传递均由消息代理（Web API 的一个明显分离的子系统）处理。
  • 图像上传和处理：调整大小并存储 FarmBot 板载摄像头捕获的图像。

• 一般来说，REST API 不控制FarmBot。设备控制由Message Broker、CeleryScript和FarmBot JS处理。

规格

• Web 框架：Ruby on Rails
• 授权机制：JSON Web 令牌
• 部署方法：12 因素
• API 架构风格：休息
• 数据库：PostgreSQL
• 测试框架：规范
• 文件存储机制：Google Cloud Storage或文件系统（可配置）
• 错误监控：防滚架（可选）
• 操作系统：Ubuntu（不可配置）
• 持续集成系统：圆圈 CI（可选）

资源

• 资源是可以从服务器下载并由 FarmBot、人类和第三方工具用于存储 FarmBot 相关信息的 JSON 文档。每个资源都有一个 URL，用于访问 URL 的HTTP 动词将决定服务器如何处理请求

• 截至 2024 年 4 月，该 API 管理以下资源：

  资源 描述 分页？
  ai_feedbacks：对自动生成提示结果的积极/消极反应。
  alerts：信息中心的单个项目。仅对站点管理员有用。：是的
  curves：基于时间的植物水分/高度/蔓延数据表。：是的
  device：设备账户设置。
  farm_events：根据时间执行序列或方案。例如：“每 6 小时执行一次此序列”。：是的
  farmware_envs：用于持久存储的键/值对。：是的
  fbos_config：FarmBot OS 的配置。
  firmware_config：Arduino 固件配置
  folders：序列的组织。
  global_bulletins：（高级）针对服务器所有用户的公告
  images：有关 FarmBot 拍摄的照片的元数据。
  logs：来自设备的消息。
  peripherals：关于输出硬件的元数据。：是的
  pin_bindings：将 I/O 引脚绑定到序列执行。：是的
  plant_templates：保存下来的花园中的一株植物。不是真正的植物。：是的
  points：表示花坛上的已保存点。此资源包含所有点类型：植物、杂草、工具槽和通用点。
  point_groups：根据标准或预定义点集收集的点（例如：“所有杂草”、“我的罗勒植物”等）：是的
  regimens：根据方案开始日期的偏移量执行序列。：是的
  saved_gardens：花园中植物的预先排列配置。：是的
  sensor_readings：来自传感器的单个读数，记录到 API。：是的
  sensors：有关输入硬件的元数据。：是的
  sequence_versions：已发布序列版本以供共享。
  sequences：在序列编辑器中创建的命令。
  telemetries：历史 FarmBot OS 状态信息。
  tokens：用户或设备与 API 之间共享的授权/身份验证秘密。
  tools：安装到龙门架或工具槽 (UTM) 的物理对象。：是的
  users：设备运营商数据，例如注册电子邮件。
  web_app_config：用户界面偏好设置。
  webcam_feeds：关于外部网络摄像头的元数据（流 URL）：是的
  wizard_step_results：设置向导结果数据。

其他端点

• 端点 描述
  ai：提出自动生成请求。
  corpus：JSON 格式的所有 Celery Script 节点类型的词汇表。
  demo_account：创建一个模拟账户。
  export_data：上面列出的所有资源的转储。
  featured_sequences：推广可供导入的公开共享序列。
  feedback：提交反馈。
  global_config：为服务器的所有用户进行配置。
  password_resets：请求重置密码。
  public_key：（高级）API 服务器拥有的公共加密密钥。
  releases：FarmBot OS 发布。
  storage_auth：（高级）Google Cloud Storage 的策略对象。

示例请求

• 如果我们希望将设备名称更改为“Carrot Overlord”，我们可以PUT对 URL执行 HTTP 操作https://my.farm.bot/api/device/325，请求主体如下：

{
  "name": "Carrot Overlord"
}

• 这样的请求将生成以下 JSON HTTP 响应：

{
  "id": 325,
  "name": "Carrot Overlord",
  "timezone": "America/Curacao",
  "last_saw_api": null,
  "last_saw_mq": null,
  "tz_offset_hrs": -4,
  "fbos_version": null,
  "throttled_until": null,
  "throttled_at": null
}

分页

• 一些 API 端点支持对请求进行分页GET，以将结果分成固定长度的较小“页面”。要发出分页请求，请将页面大小（例如：）和页码（例如：）的查询字符串附加到请求中。per=10page=3

• 例如，要下载sensor_readings页面大小为 10 个项目的第三页：

GET https://my.farm.bot/api/sensor_readings?page=3&per=10

点端点

• 虽然 REST API 在处理资源方面相对统一，plants但 、weeds、tool_slots和 genericpoints都属于同一/api/points端点。此端点还具有其他端点所没有的一些附加功能。

批量删除

• 若要在一次请求中删除多个点资源，请用逗号分隔点 ID：

DELETE https://farm.bot/api/points/1,4,23

• 删除积分后，在删除后 2 个月内仍可查看积分。这对于与剔除积分和历史记录相关的工具非常有用。

过滤

• points 端点支持一个特殊的?filter= 查询参数。此参数有三个选项：

  • ?filter=all返回已存档和活动点。
  • ?filter=old仅返回已存档的点。
  • ?filter=kept仅返回活动（未存档）点。这是索引端点 ( ) 的默认行为/api/points。

生成 API 令牌

• 您必须在请求标头token下将字符串传递到大多数 HTTP 请求中Authorization。以下是获取令牌的一些方法。另请参阅我们的Web 应用 API 示例

curl -H "Content-Type: application/json" \
 -X POST \
 -d '{"user":{"email":"test123@test.com","password":"password123"}}' \
 https://my.farm.bot/api/tokens


// Since the API supports [CORS](http://enable-cors.org/), you can generate your
// token right in the browser. Here's an example:

$.ajax({
    url: "https://my.farm.bot/api/tokens",
    type: "POST",
    data: JSON.stringify({user: {email: 'admin@admin.com', password: 'password123'}}),
    contentType: "application/json",
    success: function (data) {
                 // You can now use your token:
                 var MY_SHINY_TOKEN = data.token.encoded;
             }
});


import requests
response = requests.request(
    method='POST',
    url='https://my.farm.bot/api/tokens',
    headers={'content-type': 'application/json'},
    json={'user': {'email': 'admin@admin.com', 'password': 'password123'}})
TOKEN = response.json()['token']['encoded']

• 响应内容如下：

{
    "token": {
        "unencoded": {
            ...
            "iat": 1459109728,
            // USE THIS AS YOUR USERNAME WHEN LOGGING INTO THE MESSAGE BROKER:
            "bot": "device_456",
            "jti": "922a5a0d-0b3a-4767-9318-1e41ae600352",
            "exp": 1459455328
        },
        "encoded":
        // THE IMPORTANT PART IS HERE (shortened for clarity):
         "eyJ0eXAiOiJ...Ry7CiA"
    }
}

• 为了便于阅读，响应以 JSON 格式提供。对于Authorization标头，您只能使用data.token.encoded。在此示例中，它是以 开头的字符串eyJ0eXAiOiJ...