管理API文档
注意:Admin API版本v1/ Admin / API /v1/和v2/ Admin / API /v2/端点已弃用,并将在GET的未来版本中删除。请使用新的Admin API版本v3端点/ Admin / API /v3/。
Grafana Enterprise Traces (GET)提供了一个管理HTTP API,用于管理租户和令牌等集群资源。
API操作
API支持大多数资源的标准CRUD(创建、读取、更新和删除)操作。创建是通过帖子
请求,读取得到
请求,更新把
请求,并删除via删除
请求。当运行Admin API的多个实例时,我们建议启用领导者选举,以便所有突变都发生在单个领导者选举的实例上。
写一致性(If-Match和ETag报头)
为确保以避免意外覆盖的方式传播并发更改,可以使用If-Match
头对于所有改变数据的请求都是必需的。中要发送的资源的当前版本If-Match
标题中可以找到ETag
所有返回头信息得到
而且把
在响应体中返回单个资源的请求。
的值,这里有几个示例ETag
头使用旋度
.第一个例子使用了这个参数- - - - - - -
将所有标头写入标准输出,然后解析ETag
头。
curl -u:$API_TOKEN - sd - -o /dev/null http://localhost:8080/admin/api/v3/accesspolicies/{name} | grep -i ETag | cut -d " " -f
第二个示例使用-我
选项打印标题和响应有效负载。
curl -u:$API_TOKEN -i http://localhost:8080/admin/api/v3/accesspolicies/{name}
当发出更改数据的请求时,请确保包含双引号("
的值If-Match
头。因此,例如,下面是一个更新名为the-access-policy
,目前版本1
:
curl -u:$API_TOKEN -X PUT -H 'If-Match: "1"' http://localhost:8080/admin/api/v3/accesspolicies/the-access-policy——data '{"status": "active", "realms": [{"tenant": "traces-enterprise-dev", "cluster": "traces-enterprise-dev"}], "scopes": ["traces:write"]}'
可选的通配符“*”
可能被传递为If-Match
版本,该版本有效地禁用了写一致性保护,并允许更新任何当前版本。
集群API
集群列表
GET / admin / api / v1 /集群
GET / admin / api / v2 /集群
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /集群
代替。
GET / admin / api / v3 /集群
回应:
{"items": [{"name": "", //集群名称"display_name": "", //集群显示名称"created_at": "", //日期创建"kind": "", //集群类型"base_url": "" //集群的基础URL,可选}…], "type": "cluster"}
例子:
$ curl -u:$API_TOKEN http://localhost:8080/admin/api/v3/clusters | jq {"items": [{"name": "traces-enterprise-dev", "display_name": "traces-enterprise-dev", "created_at": "2020-07-13T16:50:41.953793Z", "kind": "traces", "base_url": ""}], "type": "cluster"}
获取集群
GET / admin / api / v1 /集群/{名称}
GET / admin / api / v2 /集群/{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /集群/{名称}
代替。
GET / admin / api / v3 /集群/{名称}
注:
- 没有
ETag
集群响应的报头,因为集群是不可变的。
回应:
{"name": "", //集群名称"display_name": "", //集群显示名称"created_at": "", //日期创建"kind": "", //集群类型"base_url": "" //集群的Base URL,可选}
例子:
$ curl -u:$API_TOKEN http://localhost:8080/admin/api/v3/clusters/traces-enterprise-dev | jq {"name": "traces-enterprise-dev", "display_name": "traces-enterprise-dev", "created_at": "2020-07-13T16:50:41.953793Z", "kind": "traces", "base_url": ""}
租户API
模型
租户模型由以下字段组成:
的名字
:租户的机器可读名称。长度必须在3到64个字符之间,且只能包含以下字符:[a-z0-9 _)
.一旦设置,这个字段是不可变的。display_name
:租户的可读名称。它可以包含任何一组字符,并且可以更改。状态
:该租户的当前状态。它可以有以下值:活跃的
不活跃的
未知的
集群
:此租户作用域的Grafana Enterprise Traces集群的名称。您将只能从这个集群写入/查询这个租户。限制
:当前不支持,不影响租户使用。
租户名单
GET / admin / api / v1 /实例
GET / admin / api / v2 /租户
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /租户
代替。
GET / admin / api / v3 /租户
注:
- 对象中仅返回租户
活跃的
的地位。包括所有的租户不活跃的
1使用查询参数include-non-active = true
回应:
{“物品”:[{“名称”:“<字符串>”,“display_name”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“状态”:“<字符串>”,“集群”:“<字符串>”,“限制”:{…}},…], "type": "tenant"}
例子:
curl - u:美元API_TOKEN localhost: 8080 / admin / api / v3 /租户|金桥{“物品”:[{" name ":“traces-enterprise-dev”、“display_name”:“Grafana企业dev租户痕迹”,“created_at”:“2020 - 07 - 13 t17:37:59.341728283z”,“状态”:“活跃”,“集群”:“traces-enterprise-dev”、“限制”:{“ingestion_rate”:0,“ingestion_burst_size”:0,“max_series_per_query”:0,“max_global_series_per_user”:0,“max_global_series_per_metric”:0,“ruler_max_rules_per_rule_group”:0,“ruler_max_rule_groups_per_tenant”:0}}], "type": "tenant"}
创建租户
发布/管理/ api / v1 /实例
发布/管理/ api / v2 /租户
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点发布/管理/ api / v3 /租户
代替。
发布/管理/ api / v3 /租户
目录中的租户名称是唯一的,因此不能创建与已存在的租户名称相同的新租户不活跃的
状态。要重用非活动租户名称,请重新启用不活跃的
租户通过将其状态更新为活跃的
.要进行此更改,请使用更新的房客端点。
在通过此API调用创建租户时,不需要指定状态
字段,因为状态总是被API覆盖活跃的
.
例子:
curl -u:$API_TOKEN localhost:8080/admin/api/v3/tenants \——data '{"name": " Traces - Enterprise -dev", "status": "active", display_name": "Grafana Enterprise Traces dev tenant", "cluster": " Traces - Enterprise -dev"}'
更新的房客
把/ admin / api / v1 /实例/{名称}
把/ admin / api / v2 /租户/{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点把/ admin / api / v3 /租户/{名称}
代替。
把/ admin / api / v3 /租户/{名称}
注:
- 的
的名字
在更新期间将忽略请求体中对象的字段。 - 的
created_at
字段在更新期间不能被修改。 If-Match
需要匹配当前版本的报头。
回应:
{" name ": " <字符串>”,“display_name”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“状态”:“<字符串>”,“集群”:“<字符串>”,“限制”:{…}}
例子:
curl -u:$API_TOKEN localhost:8080/admin/api/v3/tenants/ Traces - Enterprise -dev \ -X PUT -H 'If-Match: "123" ' \——data '{"display_name": "Grafana Enterprise Traces dev tenant TEST", "status": "active", "display_name": "Grafana Enterprise Traces dev tenant TEST", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "active", "cluster": " Traces - Enterprise -dev", "limits": {" ingestion_rate": 0, "ingestion_burst_size":0, "max_series_per_query": 0, "max_global_series_per_user": 0, "max_global_series_per_metric": 0, "ruler_max_rules_per_rule_group": 0, "ruler_max_rule_groups_per_tenant": 0}}
让租户
得到/ admin / api / v1 /实例/{名称}
GET / admin / api / v2 /租户/{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /租户/{名称}
代替。
GET / admin / api / v3 /租户/{名称}
注:
- 类型中返回租户的当前版本
ETag
响应的头。
回应:
{" name ": " <字符串>”,“display_name”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“状态”:“<字符串>”,“集群”:“<字符串>”,“限制”:{…}}
例子:
$ curl -u:$API_TOKEN localhost:8080/admin/api/v3/tenants/ Traces - Enterprise -dev | jq {"name": " Traces - Enterprise -dev", "display_name": "Grafana Enterprise Traces dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "active", "cluster": " Traces - Enterprise -dev", "limits": {"ingestion_rate": 0, "ingestion_burst_size": 0, "max_series_per_query": 0, "max_global_series_per_user": 0, "max_global_series_per_metric": 0, "ruler_max_rules_per_rule_group":0, "ruler_max_rule_groups_per_tenant": 0}}
删除租户
删除/ admin / api / v1 /实例/{名称}
删除/ admin / api / v2 /实例/{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。在Admin API v3版本中,删除操作不再受支持,并已被软删除所取代。使用端点把/ admin / api / v3 /租户/{名称}
与“状态”:“不活跃”
代替。此操作将使租户失活,后续对该租户的HTTP请求将失败,并显示401未授权的HTTP状态码。要重新启用租户,请使用端点把/ admin / api / v3 /租户/{名称}
与“状态”:“活跃”
.
把/ admin / api / v3 /租户/{名称}
{"status": "inactive", "cluster": ""}
注:
If-Match
需要匹配当前版本的报头。
例子:
curl -u:$API_TOKEN localhost:8080/admin/api/v3/tenants/ Traces - Enterprise -dev \ -X PUT -H 'If-Match: "123" ' \——data '{"status": "inactive", "cluster": " Traces - Enterprise -dev"}' | jq {" name": " Traces - Enterprise -dev", "display_name": "Grafana Enterprise Traces dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "inactive", "cluster": " Traces - Enterprise -dev",}
访问策略API
列出访问策略
得到/ admin / api / v1 / accesspolicies
得到/ admin / api / v2 / accesspolicies
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点得到/ admin / api / v3 / accesspolicies
代替。
得到/ admin / api / v3 / accesspolicies
注:
- 对象中的访问策略
活跃的
的地位。获取所有访问策略,包括不活跃的
1使用查询参数include-non-active = true
回应:
{“物品”:[{“名称”:“<字符串>”,“display_name”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“状态”:“<字符串>”,“领域”:[{“租户”:“<字符串>”,“集群”:“<字符串> "}),“范围”:[" <字符串> ",…},…], "type": "access_policy"}
创建访问策略
发布/管理/ api / v1 / accesspolicies
发布/管理/ api / v2 / accesspolicies
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点发布/管理/ api / v3 / accesspolicies
代替。
发布/管理/ api / v3 / accesspolicies
有效载荷:
{" name ": " <字符串>”,“display_name”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“领域”:[{“租户”:“<字符串>”,“集群”:“<字符串> "}),“范围”:[" <字符串> ",…]}
对象中的访问策略名称是唯一的,因此不能创建与已存在的访问策略名称相同的新访问策略不活跃的
状态。要重用非活动访问策略名称,请重新启用不活跃的
访问策略,将其状态更新为活跃的
.要进行此更改,请使用更新访问策略端点。
在通过此API调用创建访问策略时,不需要指定状态
字段,因为状态总是被API覆盖活跃的
.
领域
域指定访问策略允许请求的租户/集群对:
租户
:必须设置为已存在的租户或*
.*
表示对所有租户的访问。集群
:必须与已存在的集群匹配。
作用域
作用域指定分配给此访问策略的令牌在调用GET API时能够执行哪些操作。
痕迹:阅读
:查看租户数据的权限痕迹:写
:对租户的写权限管理
:管理员操作权限
更新访问策略
把/ admin / api / v1 / accesspolicies /{名称}
把/ admin / api / v2 / accesspolicies /{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点把/ admin / api / v3 / accesspolicies /{名称}
代替。
把/ admin / api / v3 / accesspolicies /{名称}
注:
有效载荷:
{“display_name”:“<字符串>”,“状态”:“<字符串>”,“领域”:[{“租户”:“<字符串>”,“集群”:“<字符串> "}),“范围”:[" <字符串> ",…]}
获取访问策略
GET / admin / api / v1 / accesspolicies /{名称}
GET / admin / api / v2 / accesspolicies /{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 / accesspolicies /{名称}
代替。
GET / admin / api / v3 / accesspolicies /{名称}
注:
- 控件中返回访问策略的当前版本
ETag
响应的头。
回应:
{" name ": " <字符串>”,“display_name”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“状态”:“<字符串>”,“领域”:[{“租户”:“<字符串>”,“集群”:“<字符串> "}),“范围”:[" <字符串> ",…]}
删除访问策略
删除/ admin / api / v1 / accesspolicies /{名称}
删除/ admin / api / v2 / accesspolicies /{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。在Admin API v3版本中,删除操作不再受支持,并已被软删除所取代。使用端点把/ admin / api / v3 / accesspolicies /{名称}
与“状态”:“不活跃”
代替。此操作将使访问策略失效,后续使用关联令牌的HTTP请求将失败,并显示401未授权的HTTP状态码。要重新启用访问策略,请使用端点把/ admin / api / v3 / accesspolicies /{名称}
与“状态”:“活跃”
.
把/ admin / api / v3 / accesspolicies /{名称}
注:
If-Match
需要匹配当前版本的报头。
例子:
curl -u:$API_TOKEN localhost:8080/admin/api/v3/tokens/accesspolicies/traces-enterprise-ap \ -X PUT -H 'If-Match: "123" ' \——data '{"status": "inactive", "realms": [{"tenant": "traces-enterprise-dev", "cluster": "traces-enterprise-dev"}], "scopes": ["traces:write"]}' | jq {" name": "traces-enterprise-ap", "created_at": "2022-02-11T16:55:43.598543386Z", "status": "inactive", "realms": [{"tenant": "traces-enterprise-dev", "cluster": "traces-enterprise-dev"}], "scopes": ["traces:write"]}
令牌API
列表标记
GET / admin / api / v1 /令牌
GET / admin / api / v2 /令牌
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /令牌
代替。
GET / admin / api / v3 /令牌
注:
- 对象中仅返回标记
活跃的
的地位。获得所有代币,包括不活跃的
1使用查询参数include-non-active = true
回应:
{“物品”:[{“名称”:“<字符串>”,“display_name”:“<字符串>”,“created_by”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“状态”:“<字符串>”,“access_policy”:“<字符串>”,“过期”:“<字符串> rfc3339 "},…], "type": "token"}
创建令牌
发布/管理/ api / v1 /令牌
发布/管理/ api / v2 /令牌
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点发布/管理/ api / v3 /令牌
代替。
发布/管理/ api / v3 /令牌
有效载荷:
{"name": "", "display_name": "", "created_at": "", "access_policy": "", "expiration": ""}
对象中的令牌名称是唯一的,因此不能创建与已存在的令牌同名的新令牌不活跃的
状态。要重用非活动令牌名称,请重新启用不活跃的
令牌,将其状态更新为活跃的
.要进行此更改,请使用把/ admin / api / v3 /令牌/{名称}
端点。
在通过此API调用创建令牌时,不需要指定状态
字段,因为状态总是被API覆盖活跃的
.
获得令牌
GET / admin / api / v1 /令牌/{名称}
GET / admin / api / v2 /令牌/{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /令牌/{名称}
代替。
GET / admin / api / v3 /令牌/{名称}
注:
- 对象中返回令牌的当前版本
ETag
响应的头。
回应:
{" name ": " <字符串>”,“display_name”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“状态”:“<字符串>”,“access_policy”:“<字符串>”,“过期”:“<字符串> rfc3339 "}
删除令牌
删除/ admin / api / v1 /令牌/{名称}
删除/ admin / api / v2 /令牌/{名称}
弃用:这些端点已弃用,并将在GET的未来版本中删除。在Admin API v3版本中,删除操作不再受支持,并已被软删除所取代。使用端点把/ admin / api / v3 /令牌/{名称}
与“状态”:“不活跃”
代替。此操作将使令牌失效,后续使用令牌的HTTP请求将失败,并显示401未授权的HTTP状态码。若要重新启用令牌,请使用端点把/ admin / api / v3 /令牌/{名称}
与“状态”:“活跃”
.
把/ admin / api / v3 /令牌/{名称}
{"status": "inactive"}
注:
If-Match
需要匹配当前版本的报头。
例子:
curl -u:$API_TOKEN localhost:8080/admin/api/v3/tokens/ Traces - Enterprise - Token \ -X PUT -H 'If-Match: "123" ' \——data '{"status": "inactive"}' | jq {" name": " Traces - Enterprise - Token", "display_name": "Grafana Enterprise Traces Dev Token", "created_at": "2022-02-11T16:59:36.275826382Z", "status": "inactive", "access_policy": " Traces - Enterprise -ap", "expiration": "2050-01-01T00:00:00Z"}
许可证的API
许可证列表
GET / admin / api / v1 /许可证
GET / admin / api / v2 /许可证
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /许可证
代替。
GET / admin / api / v3 /许可证
回应:
{“物品”:[{“名称”:“<字符串>”,“display_name”:“<字符串>”,“created_by”:“<字符串>”,“created_at”:“<字符串> rfc3339”,“令牌”:{“jti”:“<字符串>”,“国际空间站”:“<字符串>”,“子”:“<字符串>”,“iat”:“< int64 >”,“经验”:“< int64 >”,“nbf”:“< int64 >”,“lexp”:“< int64 >”,“盖子”:“<字符串>”,“max_users”:“< int64 >”,“included_admins”:“< int64 >”,“included_viewers”:“< int64 >”,“lic_exp_warn_days”:“< int64 >”,“刺激”:[" <字符串> ",…),“公司”:“<字符串>”,“鼻涕虫”:“<字符串 >", } }, ...], "type": "license"}
特征检测API
获取产品和特性信息
GET / admin / api / v1 /功能
GET / admin / api / v2 /功能
弃用:这些端点已弃用,并将在GET的未来版本中删除。使用端点GET / admin / api / v3 /功能
代替。
GET / admin / api / v3 /功能
回应:
{" name ": " <字符串>”,“版本”:“<字符串>”,“功能”:{“<字符串>”:“<字符串>”,…}}
示例响应:
{" name ":“获得”,“版本”:“1.1”,“功能”:{“debug_export”:“v1”,“editable_access_policies”:“v1”、“editable_tenants”:“v1”、“lbac”:“v1”、“self_monitoring”:“v1”、“federated_rules”:“v1”}}