設定 API

您可以使用 IBM Cloud® Schematics API 在 IBM Cloud 中自動執行 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 記號。

ID 類型和選項
鑑別選項	說明
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 金鑰。

建立 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`:Authorization：Basic [Yng6Yng=^] `Yng6Yng=` 等於使用者名稱 `bx` 和密碼 `bx` 的 URL授權。
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`，並依照命令列介面（CLI）輸出中的指示，透過網頁 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"
}

擷取您正在使用之記號的帳戶 ID。

請將 <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>",
            }
        }
        ]
}

產生包含 IBM Cloud 認證及您要使用之帳戶 ID 的新 IBM Cloud IAM 記號。

如果您使用 IBM Cloud API 金鑰，則必須使用為其建立 API 金鑰的 IBM Cloud 帳戶 ID。若要存取 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=` 等同於 URL 編碼的授權資訊，對應的使用者名稱為 `bx`，密碼為 `bx`。
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」欄位中找到刷新憑證。

使用 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。若要擷取工作區 ID，請執行 `ibmcloud schematics workspace list`

如需受支援 APIs 的清單，請檢閱 IBM Cloud Schematics API 文件。

透過 API 刷新 IBM Cloud IAM 存取憑證並取得新憑證

IBM Cloud® Identity and Access Management (IAM) 存取標記會在一小時後過期。必須定期重新整理存取記號才可確保對 IBM Cloud API 的存取權。您可以依照相同的步驟取得新的憑證。

開始之前，請確認您擁有有效的 IBM Cloud IAM 刷新憑證，或可 used to request a new access token 的 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 記號，或想要取得新的重新整理記號，請使用下列步驟。

使用重新整理記號或 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=` 等同於 URL 編碼的授權資訊，對應的使用者名稱是 `bx`，密碼是 `bx`。
使用重新整理記號時的內文	:`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 帳戶 ID。新增 `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」欄位中找到刷新憑證。

請使用上一步驟取得的存取憑證，繼續參閱 IBM Cloud Schematics API 文件。