设置 API

您可以在 IBM Cloud 中使用 IBM Cloud® Schematics API 自动运行 Schematics 功能。 要使用 CLI，请参阅 准备使用 CLI。

要了解支持的 IBM Cloud® Schematics APIs、API 端点以及所需的 API 标头和主体信息，请参阅 Schematics API 文档。

使用 Schematics API

了解如何使用 Identity and Access Management 令牌来验证 IBM Cloud® Schematics API。

要使用 IBM Cloud Schematics API，必须提供使用 IBM Cloud 凭证生成的 IBM Cloud® Identity and Access Management (IAM) 令牌。 根据您向 IBM Cloud 进行认证的方式，可以在下列选项之间进行选择，以自动创建 IBM Cloud IAM 令牌。

标识类型和选项
认证选项 描述
IBM Cloud 用户名和密码 您可以按照本主题中的步骤，完全自动化地创建您的 IBM Cloud IAM访问令牌。 如果使用 MFA 向 IBM Cloud 进行认证，那么无法完全自动创建 IBM Cloud IAM 令牌，因为 MFA 需要与 Web 浏览器进行手动交互。 若要完全自动化生成您的 IBM Cloud IAM令牌，您必须改用 IBM Cloud API密钥。
IBM Cloud API 密钥 作为使用 IBM Cloud 用户名和密码的替代方法，您可以 使用 IBM Cloud API 密钥。IBM Cloud API 密钥特定于为其生成的 IBM Cloud 帐户。 要访问在 IBM Cloud API 密钥所基于的帐户以外的其他帐户中创建的工作空间，必须为该帐户生成 API 密钥。
  1. 创建 IBM Cloud IAM 访问令牌。

API 令牌请求的请求主体取决于 IBM Cloud 认证方法。

您可以在 API 输出中的“access_token”字段中找到 IBM Cloud 的 IAM 令牌。 请记下 IBM Cloud IAM 令牌以在后续步骤中用于检索更多头信息。

POST `https://iam.cloud.ibm.com/identity/token`
表
输入参数 值
头 : Content-Type: application/x-www-form-urlencoded:授权: 基本 [Yng6Yng=^]
Yng6Yng= 等于用户名 bx 和密码 bxURL授权。
IBM Cloud 用户名和密码的主体 :grant_type: password:response_type: cloud_iam uaa:username: 您的 IBM Cloud username.: password: 您的 IBM Cloud password.: uaa_client_id: cf：uaa_client_secret:
添加 uaa_client_secret 键，不指定其值。
IBM Cloud API 密钥的主体 :grant_type: urn:ibm:params:oauth:grant-type:apikey:response_type: cloud_iam uaa:apikey: IBM Cloud API 密钥:uaa_client_id: cf:uaa_client_secret:
添加未指定值的 uaa_client_secret 密钥。
IBM Cloud 一次性通行码的主体 :grant_type:urn:ibm:params:oauth:grant-type:passcode:response_type: cloud_iam uaa:passcode: 您的 IBM Cloud 一次性密码。 运行 ibmcloud login --sso，并按照命令行输出中的说明，通过网页 browser.:uaa_client_id: cf 获取一次性验证码：uaa_client_secret:
添加 uaa_client_secret 键，不指定其值。

示例输出

{
"access_token": "<iam_access_token>",
"refresh_token": "<iam_refresh_token>",
"uaa_token": "<uaa_token>",
"uaa_refresh_token": "<uaa_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1493747503
"scope": "ibm openid"
}
  1. 检索您正在使用的令牌的帐户标识。

将 <iam_access_token> 替换为上一步骤中从 API 输出结果的 access_token 字段中获取的 IAM 令牌。 在您的 API 输出中，您可以在 resources.metadata.guid 字段中找到您的 IBM Cloud 账户的 ID。

GET https://accounts.cloud.ibm.com/coe/v2/accounts
输入参数以获取 IBM Cloud 帐户 ID。
输入参数 值
头 :Content-Type: application/json:Authorization: bearer <iam_access_token>:Accept: application/json

示例输出

{
    "next_url": null,
    "total_results": 5,
    "resources": [
        {
            "metadata": {
                "guid": "<account_ID>",
                "url": "/coe/v2/accounts/<account_ID>",
                "created_at": "2020-09-29T02:49:41.842Z",
                "updated_at": "2020-08-16T18:56:00.442Z",
                "anonymousId": "1111a1aa1a1111a1aa11aa11111a1111"
            },
            "entity": {
                "name": "<account_name>",
            }
        }
        ]
}
  1. 生成新的 IBM Cloud IAM 令牌，该令牌包含您的 IBM Cloud 凭证和要使用的帐户标识。

如果使用的是 IBM Cloud API 密钥，那么必须使用为其创建 API 密钥的 IBM Cloud 帐户标识。 要访问 Schematics 工作区或账户 B 中的操作，请登录账户 B 并创建基于账户 B 的 IBM Cloud API 密钥。

POST https://iam.cloud.ibm.com/identity/token
用于获取 IAM 令牌的输入参数。
输入参数 值
头 :Content-Type: application/x-www-form-urlencoded:Authorization: Basic Yng6Yng=[^]
Yng6Yng= 即为用户名 bx 和密码 bx 的 URL 编码授权。
IBM Cloud 用户名和密码的主体 :grant_type: password:response_type: cloud_iam uaa:username: 您的 IBM Cloud 用户名。:password: 您的 IBM Cloud 密码：uaa_client_ID: cf：uaa_client_secret:
添加一个不带值的 uaa_client_secret 键：specified.:bss_account： 您在上一步中获取的 IBM Cloud 账户ID。
IBM Cloud API 密钥的主体 :grant_type: urn:ibm:params:oauth:grant-type:apikey:response_type: cloud_iam uaa:apikey: 您的 IBM Cloud API key.:uaa_client_ID: cf:uaa_client_secret:
添加一个不带值的 uaa_client_secret 键：specified.:bss_account： 您在上一步中获取的 IBM Cloud 账户ID。
IBM Cloud 一次性通行码的主体 :grant_type:urn:ibm:params:oauth:grant-type:passcode:response_type: cloud_iam uaa:passcode: 您的 IBM Cloud 密码。:uaa_client_ID: cf:uaa_client_secret:
添加 uaa_client_secret 键，不指定其值。:bss_account: 您在上一步中获取的 IBM Cloud 账户ID。

Example output

{
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503
}

您可以在 API 输出中的“access_token”字段中找到 IBM Cloud 的 IAM 令牌，并在“refresh_token”字段中找到刷新令牌。

  1. 使用 Schematics API 列出帐户中的所有工作空间。

用于列出所有工作空间的语法

    GET https://schematics.cloud.ibm.com/v1/workspaces/

| Input parameters | Values |
| ----- |  --- |
| Header | `Authorization: bearer <iam_token>`|
{: caption="Input parameters to work with the IBM Cloud Schematics API." caption-side="top"}

用于检索有关特定工作空间的信息的语法:

GET https://schematics.cloud.ibm.com/v1/workspaces/{id}
输入参数以使用 IBM Cloud Schematics API。
输入参数 值
头 Authorization: bearer <iam_token>: 您的 IBM Cloud IAM 访问令牌。
路径 id <workspace_ID>: 工作区的 ID。 要检索工作空间标识，请运行 ibmcloud schematics workspace list
  1. 查看 IBM Cloud Schematics API 文档 以获取受支持 APIs 的列表。

通过 API 刷新 IBM Cloud IAM 访问令牌并获取新令牌

IBM Cloud® Identity and Access Management (IAM) 访问令牌一小时后失效。 必须定期刷新访问令牌才可确保对 IBM Cloud API 的访问权。 您可以按照相同的步骤获取一个新的令牌。

开始之前，请确保您拥有一个有效的 IBM Cloud IAM 刷新令牌，或者一个 IBM Cloud API 密钥，以便用于请求新的访问令牌。

  • 刷新令牌： 请按照《 使用 IBM Cloud API 自动化工作区创建和管理流程 》中的说明操作。
  • API密钥： 请按以下方式获取您的 IBM Cloud API密钥，具体方法如下。
    1. 在菜单栏中，单击管理 > 访问权 (IAM)。
    2. 单击用户页面，然后选择您自己。
    3. 在 “API 密钥”窗格中，单击 “创建 IBM Cloud API 密钥”。
    4. 输入 API 密钥的名称和描述，然后单击创建。
    5. 单击显示以查看生成的 API 密钥。
    6. 复制 API 密钥，以便可以将其用于检索新的 IBM Cloud IAM 访问令牌。

如果要创建 IBM Cloud IAM 令牌或要获取新的刷新令牌，请执行以下步骤。

  1. 使用刷新令牌或 IBM Cloud API 密钥来生成新的 IBM Cloud IAM 访问令牌。
POST https://iam.cloud.ibm.com/identity/token
新的 IBM Cloud IAM 令牌的输入参数。
输入参数 值
头 :Content-Type: application/x-www-form-urlencoded:Authorization: Basic Yng6Yng=

Yng6Yng= 相当于对用户名 bx 和密码 bx 进行 URL 编码后的授权信息。
使用刷新令牌时的主体 :grant_type: refresh_token:response_type: cloud_iam uaa:refresh_token: 您的 IBM Cloud IAM 刷新令牌。:uaa_client_ID: cf:uaa_client_secret::bss_account:：您的 IBM Cloud 帐户标识。

添加 uaa_client_secret 键，不指定其值。
使用 IBM Cloud API 密钥时的主体 :grant_type: urn:ibm:params:oauth:grant-type:apikey:response_type: cloud_iam uaa:apikey: 您的 IBM Cloud API 密钥。:uaa_client_ID: cf:uaa_client_secret: 添加 uaa_client_secret 键，不指定其值。

示例 API 输出

{
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "uaa_token": "<uaa_token>",
    "uaa_refresh_token": "<uaa_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503
}

您可以在 API 输出中的“access_token”字段中找到新的 IBM Cloud IAM 令牌，并在“refresh_token”字段中找到刷新令牌。

  1. 继续使用上一步中获取的令牌，操作 IBM Cloud Schematics API 文档。