API 概述
重要
如果您还不熟悉 API,请访问 API 使用入门 帮助页面。
重要
从22.1版本开始,我们摒弃了传统的公共OAuth1 API端点,因为它们需要不符合FIPS标准的SHA1哈希。摒弃内容包括传统的 WCF(Windows 通信框架)端点、用于这些传统端点的 Swagger 以及 OAuth1 中间件。要替换 OAuth1 端点,您可以使用 21.4 版发布且符合 FIPS 标准的旧版 API 的 OAuth2 版本。使用 OAuth2 API 时,功能体验与 OAuth1 API 相同。
OAuth2 将继续支持订阅、V1 和 V2 端点。
要详细了解转换及其影响,请访问 从 OAuth1 转换为 OAuth2 的说明 帮助页面或 转换说明 。
Server API 由 5 个 API 组成:
Subscription API :供用户与订阅、工作流和计划(作业)交互的端点。
User V2 API :供用户与凭证、输入文件和计划(作业)交互的端点。
Admin V1 API :供管理员从管理员界面获取资源的端点。
Admin V2 API :供管理员从管理员界面获取资源的端点版本 2。
Admin V3 API :端点版本 3。此版本使用 OAuth 2。
注意
除了为 V3 API 端点 添加新功能之外,我们还将 V1、订阅和 V2 端点提供 OAuth 2 使用。您过去使用的相同端点现在可作为一个 OAuth 2 的新基址。
用 OAuth 2 的情况下,Web API Address 只能为 V1、V2 和 V3 设置 。OAuth 1 的 V1 和 V2 API 文档地址为 http://{ServerHostname}/gallery/api-docs/ 。
访问 Server API 参考文档
Swagger 中提供了所有 Server API 端点的完整参考文档。
Server UI 中有两个位置可以访问 Server API 参考文档。
选择顶部工具条中的问号图标,然后选择 API 文档 。
选择您的用户名并选择 我的配置文件 > 密钥 。您可以在 API 验证序号旁边找到指向 API 文档的链接。
您还可以使用以下 URL 访问 Server API 的 API 参考文档:http(s)://serverhostname.domain/webapi/swagger
向 Server API 参考文档进行身份验证
Server API 文档是交互式的,允许您填充参数并查看响应。要使用交互功能,您必须进行身份验证。为此,请执行以下步骤:
在 Server UI 中,选择您的用户名并选择 我的配置 > 密钥 。复制要向其进行身份验证的 API 的 API 验证序号,并将它们粘贴到 API 验证序号 和 共享密钥 字段中。这些密钥将显示为 已保存 。
选择要运行的调用,填充参数,然后选择 试用 。
API 验证序号和 API 访问权限
用户访问 API 应由 Server 管理员授权。如需了解详情,请访问 允许用户访问 Server API 。在您授予用户对 API 的访问权限后,用户可以在 我的配置 页面的 密钥 选项卡上找到他们的 API 验证序号。要访问您的 API 密钥,请选择您的用户名并选择 我的配置 > 密钥 。
具有管理员角色的用户可以使用 API 验证 序号访问所有 API,包括 Subscription API、User V2 API、V1 Admin V1 API、V2 Admin V2 API 和 V3 API。
所有非管理员用户都可以使用 API 验证 序号访问 Subscription API 和 User V2 API。
所有用户都可以使用 私有工作室API 密钥来访问订阅API。
构建 API 端点
要构建 API 端点,请使用以下架构: <hostname>/webapi/
身份验证
请参阅 Server API 配置和授权 一文。
API 端点和参数
在本节中,您将找到以下端点的相关详情:
Server 会跟踪对以下系统实体所做的更改:
AppInfo(工作流)
集合
凭证
订阅
用户
UserGroup
通过 Server API 获取所记录的事件
这些实体每次更新都会生成一条事件审计记录。您可以通过公共的管理 API 端点返回这些记录。
端点
AuditEvents 的端点是
GET /admin/v1/auditlog/
它要求三个查询参数
entity
:(字符串)要查询的审计日志实体。page
:(int) 要返回的页面。pageSize
:(int) 每页要返回的记录数。
得到的反馈将是一组事件审计记录:
[ { "id": "", "entity": "", "entityId": "", "userId": "", "timestamp": "Date", "event": "", "oldValues": "", "newValues": "" } ]
返回的属性定义如下:
id
:审计事件 ID。entity
:实体的名称。entityId
:实体的实体 ID。userId
:修改实体的用户的 ID。timestamp
:创建审计事件记录的日期和时间。event
:发生的事件(插入、更新、删除)。oldValues
:在更新之前的更新属性值。newValues
:在更新之后的更新属性值。
要通过 API 运行使用
文件浏览工具
的工作流,请使用
/user/v2/inputfiles
端点上传文件。
首先向
/user/v2/inputfiles
端点发出 multipart/form-data POST 请求以发布临时文件。所需 form-data 部分的名称是inputFile
。curl --location --request POST 'http:{yourhostname}/api/user/v2/inputfiles/' \ --form 'inputFile=@/file/path/filename.csv'
接下来,对
/user/v2/workflows/{appId}/jobs/
端点执行 POST。然后在问号对象中加入文件浏览工具的
名称
。如果您不确定文件浏览工具的名称,请使用/v1/workflows/{appId}/questions
端点获取文件浏览工具的名称。value
是您的输入文件调用在响应中返回的参考 ID。
curl --location --request POST 'http:{yourhostname}/api/user/v2/workflows/{appId}/jobs' \ --header 'Content-Type: text/plain' \ --header 'Authorization: OAuth oauth_consumer_key="{consumer key}", oauth_signature_method="HMAC-SHA1", oauth_timestamp="{timestamp}", oauth_nonce="{nonce}", oauth_signature="{signature}"' \ --data-raw '{ "questions": [ { "name": "File Browse", "value": "{reference ID}" } ] "priority": "Low" }'
使用
migratable
端点跨 Server 环境迁移工作流。您可以使用它来管理开发和测试阶段的工作流部署。
首先,必须 启用迁移工作流 。将工作流标记为进行迁移后,请按照以下步骤将它们从源环境发布到目标环境的相应订阅(工作室)中。
第 1 步:获取准备迁移的工作流列表
接下来,使用以下端点获取准备迁移的工作流列表:
Environment: 源
方法: GET
端点:
api/admin/v1/workflows/migratable/?subscriptionIds={subscriptionIds}/
包括逗号分隔的
subscriptionIds
列表作为查询参数。订阅 ID 用于标识特定的工作室。
返回的结果是在指定订阅(工作室)下标记为准备迁移的工作流数组。如果不提供
subscriptionsIds
,返回的结果将包括所有标记为准备迁移的工作流。返回结果包括 3 个属性:
appId
、当前发布的
revisionId
和工作流所属的
subscriptionID
。
第 2 步:从源环境下载工作流
以下端点将工作流下载为 YXZP 文件。
Environment: 源
方法: GET
端点:
api/admin/v1/{appID}/package/
包括
appID
作为路径参数。返回结果是一个下载包形式的完整工作流。
第 3 步:在目标环境中发布工作流
以下端点将下载的工作流发布到目标环境。
环境: 目标
方法: POST
端点:
api/admin/v1/workflows/
参数 | |||
---|---|---|---|
参数 | 描述 | 类型 | 必填 |
| 新工作流的文件名。 | 字符串 | True |
| 新工作流名称。 | 字符串 | True |
| 已迁移工作流的所有者。电子邮件地址必须存在于目标环境中。 | 字符串 | True |
| 此标记用于在迁移到目标环境时验证工作流。 | 布尔值 | True |
| 此标记用于将工作流设置为公开,以在目标环境中的“我的公司的 Gallery”中显示。 | 布尔值 | True |
| 这是要迁移的工作流的源环境 appId。如果存在具有相同 sourceId 的工作流,则会在目标环境中替换该工作流。否则,将生成新的工作流。 (如果不希望指定 appID,请发送空字符串。) | 字符串 | True |
| 将工作程序标签添加到工作流,来让特定工作程序运行工作流。 (如果不希望指定工作程序,请发送空字符串。) | 字符串 | True |
| 此标记用于将工作流设置为可供目标环境中的其他用户下载。 | 布尔值 | True |
(可选)第 4 步:在源环境中重置迁移设置工作流
如果需要,您可以在目标环境中迁移工作流后,使用
migratable
端点将源环境中工作流的
此工作流已为迁移准备就绪
设置切换回
否
。
Environment: 源
方法: PUT
端点:
api/admin/v1/workflows/migratable/{appID}/
如需详细了解 Server API V3 端点和参数,请访问 Alteryx Server API V3 帮助页面。