1. 简介
2. 为何使用赫卡忒
3. 目录
4. 相关库
5. 构建环境
6. Docker 文件
7. 功能格式
8. 服务器
   • 数据库连接
   • JSON 验证
   • 自定义认证
9. API
   • 用户选项
   • 元数据
   • 数据统计
   • 管理界面
   • 模式
   • 认证
   • 风格
   • 矢量瓦片
   • 通过克隆下载
   • 通过查询下载
   • 边界
   • 下载单个要素
   • 通过 BBOX 下载多个要素
   • 要素创建
   • 增量
   • OpenStreetMap API

• HecateJS JavaScript 库和 CLI 工具，用于与赫卡忒 API 交互
• Hecate-Example 脚本，用于导入一些用于测试的假数据

如果你用赫卡忒 API 做了些酷的东西，告诉我们吧！

• 首先从 rust-lang.org 安装 Rust，这将安装当前稳定版本

curl https://sh.rustup.rs -sSf | sh

• 将 bashrc/bash_profile 源到你的 PATH 变量中

source ~/.bashrc        # Most Linux Distros, some OSX
source ~/.bash_profile  # Most OSX, some Linux Distros

• 安装 rust 的 nightly-2018-12-01 版本构建，Rocket 网络框架依赖于一些尚不包括在默认构建中的高级编译器选项。

rustup install nightly-2018-12-01
rustup default nightly-2018-12-01

• 下载并编译项目及其所有库

cargo build

• 请确保已安装数据库依赖项 postgres 和 postgis。

• 使用提供的模式文件创建 hecate 数据库。以下说明假定您已设置具有足够权限的角色 postgres。

echo "CREATE DATABASE hecate;" | psql -U postgres

psql -U postgres -f src/schema.sql hecate

• 此步骤还将创建名为 hecate 和 hecate_read 的数据库角色。如果连接失败是由于身份验证问题，则可能是因为您的 pg_hba 文件没有设置为信任本地连接。

您可以使用以下命令找到 pb_hba 文件的位置：echo "show hba_file;" | psql -U postgres

将文件替换为以下内容

local all postgres trust
local all all trust
host all all 127.0.0.1/32 trust
host all all ::1/128 trust
host replication postgres samenet trust

• 启动服务器

cargo run

• 测试其是否工作 - 应该响应为 HTTP200

curl localhost:8000

现在您将拥有一个空数据库，可以填充您自己的数据/用户帐户。

如果您想用测试数据填充数据库，请参阅 ingalls/hecate-example，其中包含用于填充测试数据的脚本。

Docker 文件旨在为用户提供一个测试环境，以便轻松运行 rust 测试。

安装 docker，然后运行

docker build .

docker run {{HASH FROM ABOVE}}

Hecate 设计为以 GeoJSON 为首的交换格式，并使用 标准 GeoJSON，并增加了一些修改和异常，如下所述。

支持的几何类型

• 点
• 多点
• 线字符串
• 多线字符串
• 多边形
• 多多边形

不支持的几何类型

• 几何集

附加成员

以下表格概述了 hecate 用于处理功能创建/修改/删除所使用的顶级成员。

给定特征的 .properties 中的键/值对 从不 直接由服务器使用，而只是简单传递给存储后端。这防止了用户属性和必需的服务器成员之间的潜在冲突。

示例

下载的功能

{
    "id": 123,
    "key": "Q1234",
    "version": 2,
    "type": "Feature",
    "properties": {
        "shop": true,
        "name": "If Pigs Could Fly"
    },
    "geometry": {
        "type": "Point",
        "coordinates": [0,0]
    }
}

下载的功能将返回特征的整数 id、当前 version 以及用户提供的 properties 和 geojson。对于下载的功能，action 不适用，它仅用于上传。

创建功能

{
    "action": "create",
    "key": "11-22-33-44-1234",
    "type": "Feature",
    "properties": {
        "shop": true,
        "name": "If Pigs Could Fly"
    },
    "geometry": {
        "type": "Point",
        "coordinates": [0,0]
    }
}

正在上传以创建的功能必须具有 action: create 属性。由于 id 和 version 尚未分配，因此必须省略。如果包含 id，则会被忽略。添加 version 属性将引发错误。

可选地，创建操作可以使用 force: true 选项执行类似 UPSERT 的操作。在此模式下，上传者必须指定 key 值。Hecate 将根据 key 值是新值还是已存在值来决定是否 INSERT 特征，如果 key 已存在，现有特征将被强制特征覆盖。请注意，此模式忽略版本检查，因此是不安全的。

强制先决条件

• 默认情况下已禁用，必须通过 自定义身份验证 明确启用
• 只能对具有 action: create 的特征执行
• 必须指定一个有效的 key

修改特征

{
    "id": 123,
    "key": "Fn4aAsJ30",
    "version": 1,
    "action": "modify",
    "type": "Feature",
    "properties": {
        "shop": true,
        "name": "If Pigs Could Fly"
    },
    "geometry": {
        "type": "Point",
        "coordinates": [0,0]
    }
}

正在上传以修改的功能必须具有 action: modify 以及 id 和 version 属性。 id 是要修改的特征的整数 id，而 version 属性是服务器存储的特征当前版本。如果上传的版本与服务器存储的版本不匹配，则修改将失败。这可以防止连续编辑冲突。

请注意，修改操作不是 增量操作，并且每次修改都必须包含具有完整 Geometry 和所有属性的完整特征。

还请注意，由于 id 池在几何类型之间共享，id 允许更改其几何类型。例如，如果 id: 1 是一个 Point，然后执行一个随后的 action: modify 与 Polygon 几何，则 id: 1 可以切换到新的 Polygon 类型。

删除特征

{
    "id": 123,
    "version": 1,
    "action": "delete",
    "type": "Feature",
    "properties": null,
    "geometry": null
}

正在上传以删除的功能必须具有 action: delete 以及 id 和 version 属性。有关这些属性的说明，请参阅上面的 修改特征。

请注意，properties 和 geometry 属性仍然需要包含。它们可以设置为 null 或它们的先前值。它们将被忽略。

恢复特征

{
    "id": 123,
    "version": 2,
    "key": "new-optional-key",
    "action": "restore",
    "type": "Feature",
    "properties": {
        "test": true,
        "random_array": [1, 2, 3]
    },
    "geometry": {
        "type": "Point",
        "coordinates": [ 12.34, 56.78 ]
    }
}

正在上传以恢复的功能必须具有 action: restore 以及 id 和 version 属性。 restore 操作仅是对已删除特征的 modify。

恢复将新给定的几何/属性放置在指定的 id 处。它不会自动将特征回滚到删除前的状态，如果需要这样做，则必须使用特征历史 API 获取删除前的状态，然后执行 restore 操作。

注意：如果特征仍然存在，则恢复将引发错误。

主连接

默认情况下，hecate 将尝试连接到 hecate@localhost:5432/hecate 进行读写操作，并同时连接到 hecate_read@localhost:5432/hecate 进行沙盒化的只读操作。

请注意，仅支持开启了postgis的PostgreSQL。

在启动hecate之前应该创建此数据库。有关设置数据库的说明，请参阅此文档的构建环境部分。

可以使用数据库标志指定自定义数据库名称、PostgreSQL用户或端口。

示例

cargo run -- --database "<USER>:<PASSWORD>@<HOST>/<DATABASE>"

cargo run -- --database "<USER>@<HOST>/<DATABASE>"

沙盒连接

还应该创建第二个只读账户，并具有从 geo 和 deltas 表中选择权限。此端点仅用于 query 端点，它允许执行任意用户查询。一个示例实现可以在 schema.sql 文档中找到

注意：确保此用户权限范围有限是数据库管理员的职责。Hecate将通过查询端点公开此用户的访问权限。

如果有多个 database_sandbox 实例，hecate 将在多个只读实例之间进行负载均衡。

cargo run -- --database_sandbox "<USER>:<PASSWORD>@<HOST>/<DATABASE>"

cargo run -- --database_sandbox "<USER>@<HOST>/<DATABASE>"

cargo run -- --database_sandbox "<USER>@<HOST>/<DATABASE>" --database_sandbox "<USER>@<HOST>/<DATABASE>"

副本连接 [可选]

最后，可以指定多个 --database_replica 连接，Hecate 将使用这些连接在多个读取实例之间进行负载均衡，从而减轻主数据库的写入操作容量。

cargo run -- --database_replica "<USER>:<PASSWORD>@<HOST>/<DATABASE>"

cargo run -- --database_replica "<USER>@<HOST>/<DATABASE>"

cargo run -- --database_replica"<USER>@<HOST>/<DATABASE>" --database_replica "<USER>@<HOST>/<DATABASE>"

默认情况下，Hecate 允许对给定的GeoJSON特征的任何属性进行操作，包括嵌套数组、映射等。

可以使用模式标志指定自定义属性验证文件。

示例

cargo run -- --schema <PATH-TO-SCHEMA>.json

注意，hecate 当前支持JSON Schema draft-04。一旦valico支持draft-06/07，我们就可以支持该规范的更高版本。

默认情况下，Hecate API对众包数据服务器最为有利。任何用户都可以访问数据/矢量瓦片，用户可以创建和管理数据，管理员可以管理用户账户。

这为大多数用户提供了一个中间地带，但所有端点都可以完全配置，并可以从完全开放的服务器运行到完全锁定。

如果默认值不适合您的意图，则可以通过传递认证配置JSON文档来覆盖默认值。

示例

cargo run -- --auth path/to/auth.json

auth.json的内容

{
    "endpoints": {
        "server": "public",
        "schema": null,
        "mvt": {
            "get": "user",
            "regen": "admin",
            "meta": null
        },
        "users": {
            "info": "admin",
            "create": "admin",
            "create_session": null
        },

        ....

    }
}

重要的是要注意，如果使用了自定义认证，每个类别必须被禁用或在其内部为每个子类别设置一个选项。不能有条件地覆盖默认选项的一部分。这是为了保护私有服务器，因为添加新的API端点是一个非破坏性更改，服务器会在启动之前检查您是否已为每个端点指定了策略或只是接受了默认值。

例如

以下模式是无效的。每个类别（模式、用户、样式）等必须指定为禁用或包含为每个子键设置认证的映射。

{
    "endpoint": {
        "schema": null
    }
}

行为类型

端点查找

注意

1. 这仅影响 public 样式。样式的 private 属性将覆盖此设置。无论此设置如何，私人样式 永远 不能公开。
2. 这是一个类别，唯一有效的选项是 null，这将完全禁用端点访问
3. OSM软件期望这些端点的认证与OSM相同。设置为非默认选项是支持的，但在使用OSM软件时可能会遇到不可预测的支持。如果您正在运行私人服务器，应完全禁用OSM支持。

GET /api

返回包含服务器元数据的JSON对象

示例

curl -X GET 'http://localhost:8000/api'

注意：分析统计数据取决于数据库是否已运行 ANALYZE。出于性能原因，尽可能从ANALYZEd统计数据中计算这些统计数据以确保快速结果。要获取更精确的统计数据，请确保您的数据库更频繁地运行 ANALYZE。这可以在数据库中手动完成，或使用 /api/data/stats/regen API。

GET /api/data/stats

返回包含服务器存储的几何形状统计数据和元数据的JSON对象

示例

curl -X GET 'http://localhost:8000/api/data/stats'

GET /api/data/stats/regen

对 geo 表执行 ANAYLZE 调用来更新全局统计。

示例

curl -X GET 'http://localhost:8000/api/data/stats/regen'

GET /api/styles

返回包含每个公开样式的引用的数组

示例

curl -X GET 'http://localhost:8000/api/styles'

GET /api/styles/<user id>

返回包含特定用户拥有的样式的数组

默认情况下，任何请求都只会返回给定用户的公开样式。

如果认证用户请求自己的样式，它将返回他们的公开和私人样式。

选项

示例

仅返回用户1的公开样式

curl -X GET 'http://localhost:8000/api/styles/1'

请求自定义样式的用户将获得公共和私有样式

curl -X GET \
    -u 'username:password' \
    'http://localhost:8000/api/styles/1'

POST /api/style

为认证用户创建一个新的私有样式

示例

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"name": "Name of this particular style", "style": "Mapbox Style Object Here"}' \
    -u 'username:password' \
    'http://localhost:8000/api/style'

DELETE /api/style/<id>

通过id删除特定的样式。用户必须经过授权，并且只能删除他们创建的样式。

选项

示例

curl -X DELETE 'http://localhost:8000/api/style/1'

GET /api/style/<id>

通过id获取特定的样式，公共样式可以未经认证请求，私有样式只能由请求的用户获取。

选项

示例

curl -X GET 'http://localhost:8000/api/style/1'

PATCH /api/style/<id>

更新样式 - 需要认证 - 用户只能更新他们自己的样式

选项

示例

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"name": "New Name", "style": "New Mapbox Style Object Here"}' \
    -u 'username:password' \
    'http://localhost:8000/api/style/1'

POST /api/style/<id>/private

更新公共样式并将其标记为私有。

注意：一旦样式是公共的，其他用户可能已经克隆了它。这不会影响在它是公共的时候创建的克隆样式。

选项

示例

curl -X POST \
    -u 'username:password' \
    'http://localhost:8000/api/style/1/private'

POST /api/style/<id>/public

将样式更新为公开。

然后它将出现在全局样式列表中的所有用户面前，其他用户将能够下载、克隆和使用它

选项

示例

curl -X POST \
    -u 'username:password' \
    'http://localhost:8000/api/style/1/public'

GET /api/schema

返回服务器使用的模式JSON对象，如果没有使用模式文件，则返回404。

示例

curl -X GET 'http://localhost:8000/api/schema

GET /api/auth

返回一个JSON对象，其中包含服务器根据默认认证规则或根据本指南中“自定义认证”部分定义的JSON认证定义的认证权限。

示例

curl -X GET 'http://localhost:8000/api/auth

仅管理员

DELETE /api/tiles

从集成瓦片缓存中删除所有瓦片

示例

curl -X DELETE 'http://localhost:8000/api/tiles

GET /api/tiles/<z>/<x>/<y>

请求给定坐标集的矢量瓦片。返回一个Mapbox矢量瓦片。

选项

示例

curl -X GET 'http://localhost:8000/api/tiles/1/1/1

GET /api/tiles/<z>/<x>/<y>/meta

返回有关给定瓦片的任何存储元数据。

选项

示例

curl -X GET 'http://localhost:8000/api/tiles/1/1/1/meta

GET /api/tiles/<z>/<x>/<y>/regen

允许经过认证的用户请求给定瓦片坐标的新瓦片，确保瓦片不会从瓦片缓存中返回。

选项

示例

curl -X GET \
    -u 'username:password' \
    'http://localhost:8000/api/tiles/1/1/1/regen

GET /api/users

获取用户列表（最多100个）或通过给定的用户前缀进行筛选。

选项

示例

curl -X GET 'http://localhost:8000/api/users

GET /api/user/create

创建一个新用户，如果用户名和电子邮件尚未被占用，则提供

选项

示例

curl -X GET 'http://localhost:8000/api/user/create?username=ingalls&password=yeaheh&[email protected]

GET /api/user/session

在给定的基本认证请求后返回新的会话cookie和uid。

示例

curl -X GET \
    -u 'username:password' \
    'http://localhost:8000/api/user/session

GET /api/user/info

允许经过认证的用户获取有关他们自己的账户信息

示例

curl -X GET \
    -u 'username:password' \
    'http://localhost:8000/api/user/info'

仅管理员

GET /api/user/<id>

通过数字用户ID获取系统内任何用户的详细信息。

请注意，返回的信息与用户可以通过 GET /api/user/info 端点查找的关于自己的信息相同。

选项

示例

curl -X GET 'http://localhost:8000/api/user/create?username=ingalls&password=yeaheh&[email protected]

仅管理员

PUT /api/user/<id>/admin

允许管理员将另一个用户添加到管理员池中。

选项

示例

curl -X PUT \
    -u 'username:password' \
    'http://localhost:8000/api/user/1/admin'

仅管理员

DELETE /api/user/<id>/admin

允许现有管理员从管理员池中移除另一个用户。

选项

示例

curl -X DELETE \
    -u 'username:password' \
    'http://localhost:8000/api/user/1/admin'

GET /api/data/clone

返回服务器上当前存储的所有功能点的以行为分隔的GeoJSON流。

注意：所有流式GeoJSON端点在流完成时都会发送单元代码传输结束，EOT (0x04)。这可以用来确保流没有提前退出。

示例

curl -X GET 'http://localhost:8000/api/data/clone

GET /api/data/query

返回与给定查询匹配的所有功能的以行为分隔的GeoJSON流。

查询必须是针对 geo 表的有效SQL查询。请注意，geo 是此端点可以访问的唯一表。仅允许读操作。

注意：所有流式GeoJSON端点在流完成时都会发送单元代码传输结束，EOT (0x04)。这可以用来确保流没有提前退出。

例如

SELECT count(*) FROM geo

SELECT props FROM geo WHERE id = 1

选项

示例

curl -X GET 'http://localhost:8000/api/data/query?query=SELECT%20count(*)%20FROM%20geo

curl -X GET 'http://localhost:8000/api/data/query?query=SELECT%20props%20FROM%20geo%20WHERE%20id%20%3D%201

边界允许通过一组预定的边界文件下载数据。

GET /api/data/bounds

返回一个可能的边界文件数组，可以使用这些文件从服务器提取数据

选项

示例

curl -X GET 'http://localhost:8000/api/data/bounds

GET /api/data/bounds/<bounds>

返回指定边界文件内的所有几何形状的行分隔GeoJSON Feature。

注意：所有流式GeoJSON端点在流完成时都会发送单元代码传输结束，EOT (0x04)。这可以用来确保流没有提前退出。

选项

示例

curl -X GET 'http://localhost:8000/api/data/bounds/us_dc

POST /api/data/bounds/<bounds>

创建或替换具有给定名称的边界。

注意：边界必须是 Polygon 或 MultiPolygon Feature GeoJSON。

选项

示例

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"type": "Feature", "properties": {}, "geometry": { "type": "Point", "coordinates": [ 1.1, 1.1 ] } }' \
    -u 'username:password' \
    'http://localhost:8000/api/data/bounds/us_dc'

DELETE /api/data/bounds/<bounds>

删除具有给定名称的边界文件。

选项

示例

curl -X DELETE \
    -u 'username:password' \
    'http://localhost:8000/api/data/bounds/us_dc'

GET /api/data/bounds/<bounds>/stats

返回与给定边界相交的几何形状的统计数据。

选项

示例

curl -X GET 'http://localhost:8000/api/data/bounds/us_dc/stats

GET /api/data/feature

根据查询参数返回单个GeoJSON Feature。

选项

示例

curl -X GET 'http://localhost:8000/api/data/feature?key=123

curl -X GET 'http://localhost:8000/api/data/feature?point=1.1324%2C-45.322

GET /api/data/feature/<id>

根据其ID返回单个GeoJSON Feature。

选项

示例

curl -X GET 'http://localhost:8000/api/data/features/1542

GET /api/data/feature/<id>/history

返回包含提供功能id的完整功能历史的数组。

选项

示例

curl -X GET 'http://localhost:8000/api/data/feature/1542/history

GET /api/data/features

在提供的BBOX内返回流式Line-Delimited GeoJSON

注意：所有流式GeoJSON端点在流完成时都会发送单元代码传输结束，EOT (0x04)。这可以用来确保流没有提前退出。

选项

POST /api/data/feature 需要认证

创建、修改或删除单个GeoJSON Feature

Feature必须遵循在特征格式中定义的格式。

特征还必须包含一个顶层字符串message属性，用于描述正在进行的更改（更改信息）

示例

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"action": "create", "message": "Random Changes", "type":"Feature","properties":{"shop": true},"geometry":{"type":"Point","coordinates":[0,0]}}' \
    -u 'username:password' \
    'http://localhost:8000/api/data/feature'

POST /api/data/features 需要认证

通过GeoJSON FeatureCollection创建、修改和/或删除多个特征

FeatureCollection中的Feature必须遵循在特征格式中定义的格式。

FeatureCollection还必须包含一个顶层字符串message属性，用于描述正在进行的更改（更改信息）

请注意，在每个FeatureCollection中允许混合create、modify和delete操作

示例

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"type":"FeatureCollection","message":"A bunch of changes","features": [{"action": "create", "type":"Feature","properties":{"shop": true},"geometry":{"type":"Point","coordinates":[0,0]}}]}' \
    -u 'username:password' \
    'http://localhost:8000/api/data/features'

GET /api/deltas

返回一个包含最后limit定义的数字的更改记录（默认：20）的数组及其相应的元数据。不包括更改记录的几何数据。请求特定的更改记录以获取几何数据。

更改记录端点有2种模式。第一种是最后n更改记录的固定列表。第二种是按时间戳列出更改记录。这两种模式的查询参数是互斥的。

限制选项

从指定的offset开始返回最后n更改记录。

其中n默认为20，可以通过使用limit参数增加到100

日期选项

返回在给定start和end参数之间的更改记录。

start参数应该是最近的TIMESTAMP，而end参数应该是时间上最远的。

例如：start > end。

   |---------|------|
Current    start   end
 Time

• 如果同时指定了start和end，则默认返回所有更改记录
• 如果指定了start或end，则返回最后20个更改记录或limit指定的数量

示例

curl -X GET 'http://localhost:8000/api/deltas

curl -X GET 'http://localhost:8000/api/deltas?offset=3

curl -X GET 'http://localhost:8000/api/deltas?offset=3&limit=100

GET /api/deltas/

返回给定更改记录的所有数据，包括几何数据，作为一个JSON对象。

选项

示例

curl -X GET 'http://localhost:8000/api/delta/4

重要注意事项

• 所有GeoJSON类型都可以通过API下载并在JOSM中查看。
• MultiPoints
  • 使用OSM Relation表示
  • 类型将是multipoint
  • 成员类型将是point
• MultiLineStrings
  • 使用OSM Relation表示
  • 类型将是 多行字符串
  • 成员将是 线条
• 当前不支持上传 Way 和 Relation 类型，尝试上传它们可能会导致不期望的结果。

以下不完整的端点列表在某种程度上与 OSM API 规范相兼容，但可能不完整/或以最小灵活性编写，以支持从 JOSM 进行编辑。请参阅代码以获取完整列表。

GET /api/capabilities

GET /api/0.6/capabilities

返回一个静态 XML 文档，描述 API 的功能。

示例

curl -X GET 'http://localhost:8000/api/capabilities

GET /api/0.6/user/details 需要认证

返回一个静态 XML 文档，描述用户未读消息的数量。每 n 分钟 JOSM 检查一次，如果有新消息，则显示在界面中，为了减少错误，它仅返回 0 消息响应。

示例

curl -X GET 'http://localhost:8000/api/0.6/user/details

PUT /api/0.6/changeset/create 需要认证

创建一个新的编辑集并设置元信息，返回打开的 id。

示例

curl \
    -X PUT \
    -d '<osm><changeset><tag k="comment" v="Just adding some streetnames"/></changeset></osm>' \
    'http://localhost:8000/api/0.6/changeset/create

GET /api/0.6/changeset/<changeset_id>/upload 需要认证

将 osm xml 数据上传到指定的编辑集

示例

curl \
    -X POST \
    -d '<diffResult version="0.6">NODE/WAY/RELATIONS here</diffResult>' \
    'http://localhost:8000/api/0.6/changeset/1/upload'

PUT /api/0.6/changeset/<changeset_id>/close 需要认证

关闭指定的编辑集，防止对其进行进一步修改

示例

curl -X PUT 'http://localhost:8000/api/0.6/changeset/1/close'