Sentry 开发者贡献指南 - Web API
整理自官方开发文档
目录
- 版本控制
- 身份验证
- Auth Tokens
- DSN Authentication
- API Keys
- 分页结果
- 分页示例
- 权限和范围
- 组织
- 项目
- 团队
- 成员
- 问题和事件
- 版本
- 请求
- HTTP 动词
- 参数和数据
Sentry API 用于向 Sentry collector 提交事件以及导出和管理数据。本文档仅涉及 Web API。
版本控制
Web API 的当前版本称为 v0，被认为处于草稿阶段。
身份验证
Auth Tokens
身份验证令牌使用 auth 头传递，并用于通过 API 以用户或组织帐户身份进行身份验证。在我们的文档中，我们有几个出现在花括号或 V 形之间的占位符，例如 {API_KEY} 或 <auth_token>， 您需要将其替换为您的身份验证令牌之一才能有效地使用 API 调用。
例如，当文档显示：
curl -H 'Authorization: Bearer {TOKEN}' https://sentry.io/api/0/projects/
如果您的身份验证令牌是 1a2b3c，那么命令应该是：
curl -H 'Authorization: Bearer 1a2b3c' https://sentry.io/api/0/projects/
您可以通过创建一个内部集成在 Sentry 中创建身份验证令牌。这也适用于自托管的 Sentry。
- https://docs.sentry.io/product/integrations/integration-platform/#internal-integrations
DSN Authentication
某些 API 端点可能允许基于 DSN 的身份验证。这通常非常有限，并且端点将描述其是否受支持。这与 Bearer token 身份验证类似，但使用您的 DSN（Client Key）。
curl -H 'Authorization: DSN {DSN}' https://sentry.io/api/0/projects/
API Keys
API keys 是一种传统的身份验证方法。它们仍然会被支持，但对于新帐户是禁用的。您应该尽可能使用 authentication tokens。
API keys 使用 HTTP Basic auth 传递，其中用户名是您的 api key，密码是空值。
例如，要获取有关您的 key 绑定到的项目的信息，您可以做出如下请求：
curl -u {API_KEY}: https://sentry.io/api/0/projects/
您必须为密码传递一个值，这就是我们示例中出现
:的原因。
分页结果
API 中的分页是通过 Link 头标准处理的：
curl -i https://sentry.io/api/0/projects/1/groups/
HTTP/1.0 200 OK
Date: Sat, 14 Feb 2015 18:47:20 GMT
Content-Type: application/json
Content-Language: en
Allow: GET, HEAD, OPTIONS
Link: <https://sentry.io/api/0/projects/1/groups/?&cursor=1420837590:0:1>;
rel="previous"; results="false",
<https://sentry.io/api/0/projects/1/groups/?&cursor=1420837533:0:0>;
rel="next"; results="true"
如果受到支持，将始终为上一页和下一页返回游标，即使这些页面上没有结果也是如此。这允许您对 API 进行查询以获取尚未发现的结果。一个使用这个的例子是当你实现轮询行为并且你想看看是否有任何新数据。我们返回 results="[true|false]" 指示符以确定您是否真的需要分页。
分页示例
以下是使用此 API 端点的分页示例：
- https://docs.sentry.io/api/events/list-an-issues-events/
此示例中的 HTTP 请求针对该问题返回 100 个事件，并在响应中包含以下 link 头：
<https://sentry.io/api/0/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="false"; cursor="0:0:1", <https://sentry.io/api/0/issues/123456/events/?&cursor=0:100:0>; rel="next"; results="true"; cursor="0:100:0"
link 响应中的一个 URL 具有 rel=next，表示下一个结果页面。它也有 results=true，这意味着有更多的结果。
基于此，下一个请求是 GET <https://sentry.io/api/0/issues/123456/events/?&cursor=0:100:0>.
此请求将再次返回该问题的下 100 个事件，并带有以下 link 头：
<https://sentry.io/api/0/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="true"; cursor="0:0:1", <https://sentry.io/api/0/issues/123456/events/?&cursor=0:200:0>; rel="next"; results="true"; cursor="0:200:0"
重复该过程，直到带有 rel=next 的 URL 具有标志 results=false 以指示最后一页。
cursor 的三个值是：游标标识符（整数，通常为 0）、行 offset 和 is_prev（1 或 0）。
权限和范围
如果你是建立在 Sentry 的 API 之上(例如使用 Auth Tokens)，你将需要特定的作用域来访问不同的 API 端点。
- https://docs.sentry.io/api/auth/
要设置 integration token 的作用域，请从下拉菜单中选择作用域。这些可以稍后编辑。
- https://docs.sentry.io/product/integrations/integration-platform/#permissions
要设置 auth token 的作用域，请在创建 auth token 时选中必要的复选框。
- https://sentry.io/api/
如果您正在寻找有关 membership 角色的信息，请访问 membership 文档。
- https://docs.sentry.io/product/accounts/membership/
组织
org:read项目
project:read
project:releases范围将允许您访问 project 和 organization release 端点。API 文档的 Releases 部分列出了可用的端点。https://docs.sentry.io/api/releases/
团队
team:read成员
member:read问题和事件
event:readPUT/DELETE 方法仅适用于
更新/删除问题。Sentry 中的事件是不可变的，只能通过删除整个问题来删除。
版本
GET/PUT/POST/DELETE | project:releases |
|---|
请注意，如果您使用
sentry-cli来管理您的版本，您将需要一个也具有org:read范围的token。
请求
所有 API 请求都应该以 /api/0/ 前缀发出，并将返回 JSON 作为响应：
curl -i https://sentry.io/api/0/
HTTP/1.0 200 OK
Date: Sat, 14 Feb 2015 18:47:20 GMT
Content-Type: application/json
Content-Language: en
Allow: GET, HEAD, OPTIONS
{"version": "0"}
HTTP 动词
Sentry 试图坚持使用适当的 HTTP 动词，但我们总是优先考虑可用性而不是正确性。
用于删除资源。参数和数据
URL 中未包含的任何参数都应编码为 JSON，其 Content-Type 为 'application/json'：
curl -i https://sentry.io/api/0/projects/1/groups/ \
-d '{"status": "resolved"}' \
-H 'Content-Type: application/json'
有时通过查询字符串指定附加参数，即使是 POST、PUT 和 DELETE 请求：
curl -i https://sentry.io/api/0/projects/1/groups/?status=unresolved \
-d '{"status": "resolved"}' \
-H 'Content-Type: application/json'