App Center API 文档

  • 项目

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center，直到它完全停用，但你可以考虑迁移到几个建议的替代方法。

详细了解支持时间线和替代方法。

App Center OpenAPI 规范 (Swagger)

App Center 公开一组完整的 API 终结点。 可以通过 App Center OpenAPI 规范浏览 App Center API。

App Center OpenAPI 规范允许使用 API 令牌进行身份验证。 通过身份验证后，可以调用 App Center API 来了解 API 并查看它返回的数据。

令牌类型：用户令牌和应用令牌

App Center 公开两种类型的 API 令牌：用户令牌和应用令牌。

用户 API 令牌具有与 App Center 用户相同的权限。 用户 API 令牌适用于与你关联的所有组织和应用。

应用 API 令牌具有“管理员”或“查看者”权限，但仅在一个应用中。

每个 App Center 帐户最多可以创建 5000 个 API 令牌。

提示

建议创建和使用应用 API 令牌，以将授权范围限制为一次一个应用， (并限制) 公开令牌的风险。 如果需要自动执行一个应用以外的某些操作，例如使用组织或共享通讯组，则应创建用户 API 令牌。

警告

不要将 API 令牌嵌入源代码。 API 令牌应被视为机密，并安全地存储。

警告

请求必须包含 POST/PUT/PATCH API 调用的有效负载正文。 对于 {} 空的有效负载正文，否则 API 调用将收到 “411 长度所需 ”错误响应。

创建 App Center 应用 API 令牌

  1. 导航到 https://appcenter.ms 并使用帐户凭据登录。

  2. 选择要 为其创建 API 令牌的应用。

  3. 在左侧，选择“设置”。

  4. 在中间面板中，从菜单列表中选择“ 应用 API 令牌 ”。

  5. 在右上角，单击“ 新建 API 令牌”。

  6. 在文本字段中，输入令牌的描述性名称。

  7. 选择应用 API 令牌的访问类型：

    完全访问权限： 完全访问权限应用 API 令牌具有该应用的管理员权限。 只有管理员才能创建完全访问权限的应用 API 令牌。

    只读： 只读应用 API 令牌具有该应用的查看者访问权限。 经理和开发人员可以创建只读的应用 API 令牌。

  8. 在面板底部，单击“ 添加新 API 令牌”。

  9. 此时会打开一个弹出窗口，其中包含应用 API 令牌。 将其复制并存储在安全位置 供以后使用。 出于安全原因，单击“ 关闭 ”按钮后，无法再次看到或生成相同的令牌。

  10. 单击“关闭”按钮。

创建 App Center 用户 API 令牌

  1. 导航到 https://appcenter.ms 并使用帐户凭据登录。

  2. 在 App Center 门户的右上角，单击帐户头像，然后选择“帐户设置”。

  3. 在中间面板中，从菜单列表中选择“ 用户 API 令牌 ”。

  4. 在右上角，单击“ 新建 API 令牌”。

  5. 在文本字段中，输入令牌的描述性名称。

  6. 选择用户 API 令牌的访问类型：

    完全访问权限： 完全访问权限用户 API 令牌具有当前帐户/组织的所有权限。 例如，如果你没有应用的经理或开发人员权限，则即使你使用的是完全访问权限用户 API 令牌，用户也无法运行测试。

    只读： 只读用户 API 令牌具有当前帐户/组织的查看者访问权限。 例如，使用只读用户 API 令牌，可以从崩溃、分析中读取数据并获取基本应用信息。 只读用户 API 令牌无法更改应用设置、触发生成、创建导出配置等。

  7. 在面板底部，单击“ 添加新 API 令牌”。

  8. 此时会打开一个弹出窗口，其中包含你的用户 API 令牌。 将其复制并存储在安全位置 供以后使用。 出于安全原因，单击“ 关闭 ”按钮后，无法再次看到或生成相同的令牌。

  9. 单击“关闭”按钮。

在 API 请求中使用 API 令牌

从应用程序向 App Center 发送 API 请求时，必须在发送到 App Center 的每个请求的 标头中包含 API 令牌。

在请求的 X-API-Token 标头属性中传递 API 令牌。

查找 App Center 应用名称和所有者名称

App Center 的某些 API 函数和 CLI 请求需要应用名称或所有者名称作为参数。

例如，从应用中删除用户的 API 调用需要以下两项： DELETE /v0.1/apps/{owner_name}/{app_name}/users/{user_email}。

可以从 App Center URL 或使用 App Center CLI 查找应用名称和所有者名称。

从 App Center URL 查找owner_name和app_name

  1. 导航到 https://appcenter.ms。
  2. 导航到你的应用。
  3. 查看应用的 URL 时，其格式 https://appcenter.ms/users/{owner-name}/apps/{app-name}为 。

所有者可以是用户或组织。 例如：

所有者 URL 所有者名称 应用程序名称
用户 https://appcenter.ms/users/AlexLerxst/apps/Caravan-01 AlexLerxst 大篷车-01
组织 https://appcenter.ms/orgs/BallardFlowers/apps/BouquetOrders-app BallardFlowers BouquetOrders-app

从 App Center CLI 查找owner_name和app_name

如果尚未安装 App Center CLI，可在 App Center CLI 文档中找到安装和使用说明。

安装后，通过运行以下命令检索你有权访问的应用列表：

appcenter apps list

App Center CLI 将显示应用列表，格式 {owner-name}/{app-name}为 。

有关命令行函数的完整列表，请参阅 App Center CLI 文档 。

将 API 令牌与 App Center OpenAPI 规范配合使用

App Center OpenAPI 规范会为你处理 API 身份验证，因此无需将 API 令牌粘贴到请求的标头中。 使用 API 令牌测试 App Center API：

  1. 导航到 App Center 的 OpenAPI 规范 ，浏览我们的 API。

  2. 在右上角，单击“ 授权 ”按钮。

  3. 在 “APIToken ”部分下，将 API 令牌粘贴到 “值 ”中，然后单击“ 授权”。

    设置 API 令牌以授权 App Center 使用

  4. 如果显示“已授权”和“注销”按钮，则表示授权成功。 在弹出窗口的右上角，单击“X”退出弹出窗口。

使用 OpenAPI (Swagger) 进行第一次 API 调用

本部分介绍如何使用 API 调用 GET /v0.1/user来使用 App Center 的 OpenAPI 页。 此 API 调用返回用户的配置文件数据。

  1. 按照 上述说明创建 API 令牌。
  2. 按照 上一部分中的说明授权 OpenAPI 规范页使用 API 令牌。
  3. 在 “帐户”下，单击 GET /v0.1/user。
  4. 在左侧角，单击“ 试用 ”按钮。
  5. 单击“参数”部分下的“执行”按钮。
  6. 太棒了！ 现在可以在“响应”部分下看到 响应 。

撤销 API 令牌

如果 API 令牌泄露，应立即撤销该令牌，以防止未经授权访问 App Center 帐户。

撤销用户 API 令牌

  1. 导航到 https://appcenter.ms。
  2. 在 App Center 门户的右上角，单击帐户头像，然后选择“帐户设置”。
  3. 在中间面板中，从菜单中选择“ 用户 API 令牌 ”。
  4. 选中要撤销的令牌旁边的框，然后单击右上角的“ 删除 ”按钮。

撤销应用 API 令牌

  1. 导航到 https://appcenter.ms。
  2. 选择要 为其吊销 API 令牌的应用。
  3. 在左侧，选择“设置”。
  4. 在中间面板中，从菜单中选择“ 应用 API 令牌 ”。
  5. 选中要撤销的令牌旁边的框，然后单击右上角的“ 删除 ”按钮。