STAC API 验证器

简介

STAC API 验证器是 STAC API 规范系列的官方验证套件。

文档

请参阅 稳定版 或 最新版 文档页面。

安装

STAC API 验证器需要 Python 3.10。

您可以从 pip 通过 PyPI 安装 STAC API 验证器

pip install stac-api-validator

然后运行它

stac-api-validator \
    --root-url https://planetarycomputer.microsoft.com/api/stac/v1/ \
    --conformance core \
    --conformance features \
    --conformance item-search \
    --collection sentinel-2-l2a \
    --geometry '{"type": "Polygon", "coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]}'

贡献

欢迎贡献。有关更多信息，请参阅 贡献指南。

用法

有关详细信息，请参阅 命令行参考。

要运行的符合性类验证通过 --conformance 参数选择。此参数可以多次使用以指定多个符合性类进行验证。即使未指定，也会始终验证 STAC API - Core 符合性类。

如果指定了 item-search、collections 和/或 features，则必须也指定 --collection 和 --geometry 参数。--collection 参数指定用于某些验证的集合名称。--geometry 应指定一个区域（AOI），该区域中集合的结果在100到20,000个之间（结果越多，运行时间越长）。

功能

工作正在进行中 -- 目前这仅验证了一部分行为

此验证套件侧重于验证STAC API交互。例如，pystac 和 stac4s 工具在验证STAC对象（目录、集合、项）方面做得很好。本套件侧重于STAC API行为验证。

STAC API中的三个关键概念是

1. 符合性类别 宣传API的功能
2. 链接关系 在Web API中的资源之间（超媒体）
3. 参数 过滤搜索结果

符合性类别在着陆页（根，/）的 conformsTo 字段中定义，向客户端宣传API中可用的功能。如果没有此字段，客户端甚至无法知道根URI是否为STAC API。

链接关系定义了如何通过父子链接导航STAC目录，并查找如OpenAPI规范等资源。虽然许多OGC API和STAC API端点具有固定值（例如，/collections），但通过超媒体发现路径更可取。

过滤结果的参数适用于Items资源以及Item Search端点。

可以在此处找到几个流行STAC API实现的当前有效性状态。

命令行参考

用法

Usage: stac-api-validator [OPTIONS]

  STAC API Validator.

Options:
  --version                       Show the version and exit.
  --log-level TEXT                Logging level, one of DEBUG, INFO, WARN,
                                  ERROR, CRITICAL
  --root-url TEXT                 STAC API Root / Landing Page URL  [required]
  --collection TEXT               The name of the collection to use for item-
                                  search, collections, and features tests.
  --geometry TEXT                 The GeoJSON geometry to use for intersection
                                  tests.
  --conformance [core|browseable|item-search|features|collections|children|filter]
                                  The conformance classes to validate.
                                  [required]
  --auth-bearer-token TEXT        Authorization Bearer token value to append
                                  to all requests.
  --auth-query-parameter TEXT     Query pararmeter key and value to pass for
                                  authorization, e.g., 'key=xyz'.
  --help                          Show this message and exit.

符合性类别item-search、features和collections需要带有集合ID的--collection参数来运行一些测试。

符合性类别item-search需要带有返回指定集合某些项的GeoJSON几何形状的--geometry。

示例

stac-api-validator \
    --root-url https://planetarycomputer.microsoft.com/api/stac/v1/ \
    --conformance core \
    --conformance item-search \
    --conformance features \
    --collection sentinel-2-l2a \
    --geometry '{"type": "Polygon", "coordinates": [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]]}'

示例输出

Validating https://cmr.earthdata.nasa.gov/stac/LARC_ASDC ...
STAC API - Core conformance class found.
STAC API - Item Search conformance class found.
warnings: none
errors:
- service-desc (https://api.stacspec.org/v1.0.0-beta.1/openapi.yaml): should have content-type header 'application/vnd.oai.openapi+json;version=3.0'', actually 'text/yaml'
- service-desc (https://api.stacspec.org/v1.0.0-beta.1/openapi.yaml): should return JSON, instead got non-JSON text
- GET Search with bbox=100.0, 0.0, 105.0, 1.0 returned status code 400
- POST Search with bbox:[100.0, 0.0, 105.0, 1.0] returned status code 502
- GET Search with bbox=100.0,0.0,0.0,105.0,1.0,1.0 returned status code 400
- POST Search with bbox:[100.0, 0.0, 0.0, 105.0, 1.0, 1.0] returned status code 400

使用参数进行授权的示例

stac-api-validator --root-url https://api.radiant.earth/mlhub/v1 --conformance core --auth-query-parameter 'key=xxx'

验证OGC API功能 - 第1部分合规性

符合“STAC API - Features”符合性类别的STAC API也将是OGC API功能 - 第1部分的合法实现。通常，此验证器侧重于STAC和OGC之间不同的API行为方面。建议实现者还使用OGC API功能 - 第1部分验证测试套件来验证合规性。

完整说明可在上述链接中找到，但运行此测试的最简单方法是

docker run -p 8081:8080 ogccite/ets-ogcapi-features10

然后，打开http://localhost:8081/teamengine/，使用用户名和密码 ogctest 登录，选择组织 OGC，规范 OGC API - Features，然后选择 开始新的测试会话，输入服务的根URL，并选择 开始。

常见错误

• 在着陆页中conformsTo不正确。这是在STAC API 0.9和1.0之间添加的。它应与OAFeat /conformance端点中的conformsTo中的值相同。
• OGC API功能在根处使用data链接关系来指向Collections端点（/collections），而不是collections链接关系。
• 链接关系service-desc和端点的媒体类型是application/vnd.oai.openapi+json;version=3.0（不是application/json），而链接关系search和端点的媒体类型是application/geo+json（不是application/json）。
• 使用OGC API "req" URL而不是"conf" URL，例如，应使用http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core，而不是http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core。

许可证

根据Apache 2.0许可证条款分发，STAC API Validator 是一款免费和开源的软件。

问题

如果您遇到任何问题，请提交问题，并附上详细描述。

鸣谢

本项目基于 @cjolowicz 的 Hypermodern Python Cookiecutter 模板生成。