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/ 。

The Web API address can be set up in System Settings.

访问 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：在更新之后的更新属性值。

Inputfiles 端点

要通过 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/

参数
参数	描述	类型	必填
`file`	新工作流的文件名。	字符串	True
`name`	新工作流名称。	字符串	True
`owner`	已迁移工作流的所有者。电子邮件地址必须存在于目标环境中。	字符串	True
`validate`	此标记用于在迁移到目标环境时验证工作流。	布尔值	True
`isPublic`	此标记用于将工作流设置为公开，以在目标环境中的“我的公司的 Gallery”中显示。	布尔值	True
`sourceId`	这是要迁移的工作流的源环境 appId。如果存在具有相同 sourceId 的工作流，则会在目标环境中替换该工作流。否则，将生成新的工作流。（如果不希望指定 appID，请发送空字符串。）	字符串	True
`workerTag`	将工作程序标签添加到工作流，来让特定工作程序运行工作流。（如果不希望指定工作程序，请发送空字符串。）	字符串	True
`canDownload`	此标记用于将工作流设置为可供目标环境中的其他用户下载。	布尔值	True

（可选）第 4 步：在源环境中重置迁移设置工作流

如果需要，您可以在目标环境中迁移工作流后，使用 migratable 端点将源环境中工作流的 此工作流已为迁移准备就绪 设置切换回否。

Environment: 源
方法： PUT
端点： api/admin/v1/workflows/migratable/{appID}/

如需详细了解 Server API V3 端点和参数，请访问 Alteryx Server API V3 帮助页面。

本节内容如下: