使用收益服務 API 管理盈餘

本文說明如何透過收益 API 而非合作夥伴中心的 UI 存取盈餘資料。 這些 API 提供了一種程式化方式，以實現合作夥伴中心匯 出資料 功能的功能。

可用的 API

查看合作夥伴結算中的所有可用 API。

先決條件

• 在 Azure 入口網站有可用的訂閱。
• 有網頁瀏覽器可以使用。
• 能夠用程式化或專用軟體呼叫 REST API。

使用 Microsoft 身分識別平台來註冊應用程式

1. 請依照指示 在 Microsoft 認證平台建立應用程式註冊。

2. 給予應用程式適當的委派權限。

   1. 在新建立的應用程式註冊中，請前往管理 → API 權限。 選擇「新增權限」。顯示
   2. 選擇「我組織使用的 API」分頁，然後查詢 AppID 「4990cffe-04e8-4e8b-808a-1175604b879f」或「Microsoft Dev Center」。權限請選擇「user_impersonation」。選擇「新增權限」。
      • 故障排除：如果搜尋開發中心 API 沒有結果，可能需要建立手動存取這些 API 所需的服務主體。 它們可以用 AzCLI 建立：

        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        

        之後，API 權限應該可以從搜尋對話框中選擇。
   3. 此外，請確保你的應用程式在 Microsoft Graph 中擁有「User.Read」權限。 如果沒有，請在 Microsoft API 標籤中選擇 Microsoft Graph 來新增。
   4. 選擇「授予管理員同意」以取得您所取得的三個權限。
   5. 你的應用程式權限應該如下（注意每個權限旁邊的綠色勾選）：

3. 為網頁平台設置一個重定向 URI。

   1. 前往管理→認證。 選擇「新增平台」。
   2. 選擇「網頁」。
   3. 在 Redirect URI 中，輸入你想用於應用程式的 URI，例如 https://localhost:3000。 把這個網址記錄下來，留待日後使用。 按下「配置」。

4. 產生一個客戶端秘密，用於取得存取權杖。

   1. 前往管理→憑證與秘密。 到「客戶端秘密」分頁，選擇「新客戶端秘密」。
   2. 輸入所需的名稱和持續時間。
   3. 選擇新增機密。
   4. 把價值記在別處。 務必將它放在安全的地方，例如鑰匙庫。 你在請求 AccessToken 和 RefreshToken 時會使用這個秘密。

取得存取權杖 - 支援多重身份驗證（MFA）的帳號

Earnings API 要求在請求中提供一個 AccessToken 作為授權持有人令牌，且前綴 Bearer <access-token> 置於授權標頭中。 你可以用你的帳號登入取得這個代幣;然而，存取權杖壽命短暫。 每次需要呼叫 API 時都登入啟用 MFA 的帳號來產生一個令牌，對於涉及自動化的工作流程來說並不實際。 這些步驟會引導你完成產生 RefreshToken 的流程。 它的壽命較長（約 3 個月），可用來取得 AccessToken。 將 RefreshToken 存放在安全位置，你可以用它程式化取得 AccessToken 來呼叫 Earnings API。 注意： RefreshToken 只能使用一次，之後即失效。 回應中會同時回傳新的 RefreshToken 和 AccessToken。 每次使用 RefreshToken 時，務必替換你安全儲存中舊有的 RefreshToken 值。

1. 透過瀏覽器取得 AuthCode。 目前這個過程必須透過網頁瀏覽器的介面來完成，無法用程式化方式完成。

   1. 請依 照此 處的範本建立一個用來取得 AuthCode 的網址。
      1. 為建立的應用程式使用租戶 ID 和客戶 ID。
      2. 將範圍設為 https://api.partner.microsoft.com/.default。
      3. 將重定向 URL 設為先前設定好的重定向 URL。 網址範本如下： https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>&scope=https%3A%2F%2Fapi.partner.microsoft.com%2F.default
   2. 前往建構網址，並使用授權使用者的憑證登入。
   3. 成功登入後，您的瀏覽器會嘗試開啟格式 <redirect-uri>/?code=<auth-code>&session_state=<state-id>#的網址。 以前面步驟的重定向 URI 範例來說，你被傳送到的 URL 應該是 https://localhost:3000/?code=<auth-code>?session_state=<state-id>#。 把回來的驗證碼存到安全的地方。
      • 由於 localhost：3000 通常沒有應用程式在監聽，瀏覽器會跳出「無法連線」的錯誤訊息。這個錯誤是預期中的，因為我們只需要手動複製先前 URL 查詢參數中的 code AuthCode 值即可。
      • 在生產解決方案中，可能會建立一個應用程式自動處理這部分的驗證流程。 例如，使用者可以進入單一頁面應用程式（SPA）的工作流程。 使用者選擇一個「登入」按鈕，會帶他們前往先前建立的網址。 登入後，SPA 會擷取 AuthCode 的值並將其儲存到保險庫。 SPA 接著利用 AuthCode 取得 RefreshToken 與 AccessToken，詳情如下。

2. 使用 AuthCode 取得 RefreshToken 和初始 AccessToken。 注意： RefreshToken 每三個月到期一次，需要重新取得並存放在某個金鑰庫中。

   1. 請依 照此處提供的範本建立 POST API 請求。
      1. 請為租戶/客戶 ID 和重導 URL 使用相同的值。
      2. 將範圍設為 https://api.partner.microsoft.com/.default offline_access。
      3. 將程式碼設定為前一步取得的 AuthCode。
      4. 將 client_secret 設為為所建立應用程式所產生的秘密。 接著，網址的結構應該如下： https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. 之後你可以用 RefreshToken 取得新的 AccessToken。

   1. 請依 照此處提供的範本建立 POST API 請求。
      1. 請對「租戶/客戶 ID」和「轉址 URL」使用相同的值。
      2. 將範圍設為 https://api.partner.microsoft.com/.default
      3. 將 refresh_token 設為前一步中取得的 RefreshToken
      4. 將 client_secret 設為為所建立應用程式所產生的秘密。

取得存取權憑證 - 非多重身份驗證帳戶

1. 利用新應用程式註冊資訊取得 AccessToken 。
   1. 請依 照此處提供的範本建立 POST API 請求。
      1. 租戶/客戶 ID 也要用相同的值
      2. 將範圍設為 https://api.partner.microsoft.com/.default
      3. 使用授權使用者的使用者名稱/密碼，URL 結構應如下： https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. 請求會回傳 AccessToken 和一個新的 RefreshToken。 務必更新 RefreshToken 的儲存值，因為你無法再使用舊值。

收益（前稱交易記錄）/付款

• 使用先前在授權標頭取得的 AccessToken 並加前綴 Bearer <access-token> ，建立新的 收益（前稱交易歷史） 或 支付 報告。

相關內容

• 使用入口網站建立可存取資源的 Microsoft Entra 應用程式和服務主體
• 使用 Microsoft 身分識別平台來註冊應用程式
• 設定客戶端應用程式以存取網頁 API