提出 HTTP 要求

重要

在對生成式 AI 進行大量投資並增強 Microsoft Copilot 的整合後，Power Virtual Agents 的功能和特性現已成為 Microsoft Copilot Studio 的一部分。

當我們更新文件和培訓內容時，某些文章和螢幕擷取畫面可能會參考 Power Virtual Agents。

在 Copilot Studio 中，您可以透過使用 HTTP 要求 節點呼叫外部 REST API 來擴展副手的功能。 當您需要從外部系統擷取資料或操縱該系統上的資料時，這會很有用。

先決條件

• 建立和編輯主題

使用 HTTP 要求節點

1. 選取新增節點 (+)，打開進階子功能表，然後選取傳送 HTTP 要求。

   

2. 在 URL 方塊中，輸入要呼叫的 API 端點的 URL。

3. 從下拉式清單選取適當的要求方法。 支援 GET、POST、PATCH、PUT 和 DELETE 方法。

   

4. 在節點的標題和正文底下，按一下編輯按鈕。 這會打開 HTTP 要求屬性窗格。

5. 您可以選擇將一個或多個標題新增至 HTTP 要求。 按一下新增按鈕以新增各個標題的索引鍵和值。

   

6. 根據預設，HTTP 要求的本文中不會傳送任何內容，但是您可以指定要在該本文上傳送的內容。

7. 在節點上，從可用的選項中選擇回覆資料類型。

   您可以提供一個範例JSON 回覆 (通常可以在您呼叫的 API 文件中找到該回覆)，該回覆將產生強型別 Power FX 變數，可讓您在製作畫布中的其他位置使用，並在 Power FX 編輯器中提供 IntelliSense 支援。 若要這樣做，請選擇從範例資料，然後按一下從範例 JSON 取得結構描述，將您的範例回覆貼到顯示的編輯器中，然後選擇確認。

   

8. 在將回覆另存為底下，選擇您希望儲存 HTTP 要求回覆的位置，可以建立新變數，也可以選擇現有變數。

在 HTTP 要求本文中傳送內容

1. 在節點的標題和正文底下，按一下編輯按鈕。 這會打開 HTTP 要求屬性窗格。

2. 在本文底下，選取適當的內容類型。 根據預設，此項會設定為無內容，要求本文中不應出現任何內容，這最常與 GET 要求一起使用。 若要將內容新增至本文，請選取其中一個可用的選項。

   

   • JSON 內容：JSON 內容可讓您在要求本文中提供 JSON 物件。 這通常在發出 POST 或 PUT 要求時使用。 選擇此選項後會顯示一個編輯器，您可以在其中輸入 JSON 內容。

     您也可以使用 Power FX 輸入指定的 JSON 內容，讓您包含動態值和參考變數。 若要執行此動作，請選取編輯 JSON按鈕，選擇公式，然後輸入 Power FX 物件 (任何已輸入的現有 JSON 將會轉換為 Power FX 物件)，當發出 HTTP 要求時，該物件將轉換為 JSON。

     

   • 原始內容：原始內容可讓您將資料的字串插入至要求本文中，此字串可以是任何您指定的內容類型。 原始內容是使用 Power FX 公式輸入的，例如下例中顯示的字串內容。

     

錯誤處理和逾時

HTTP 要求節點有多個選項用於處理 HTTP 要求可能失敗或傳回錯誤的情形。

根據預設，此功能將會「引發錯誤」。 這代表當 HTTP 要求傳回錯誤或執行失敗時，副手將停止其作業並觸發錯誤系統主題，顯示錯誤訊息。

但是，您可以將錯誤處理設定為不觸發錯誤系統主題，而是將 HTTP 狀態碼與任何錯誤回覆本文填入您指定的變數中，這樣您就可以視需要詢問這些變數，並讓主題繼續執行。 這在您希望即使特定 HTTP 要求失敗，副手也能繼續操作的情況下非常有用。

設定錯誤處理行為。

1. 在節點的標題和正文底下，按一下編輯按鈕。 這會打開 HTTP 要求屬性窗格。

2. 從錯誤處理下拉式功能表中選擇您想要的行為。

3. 如果您選擇在出錯時繼續，請設定狀態碼與錯誤回覆本文變數，從選擇器建立新變數或選取現有的變數。

   

在此程式碼範例中，如果 HTTP 要求失敗，副手會將 HTTP 狀態碼儲存在 Topic.StatusCode 變數中，並將回覆本文儲存在 Topic.ErrorResponse 變數中。 然後副手將繼續主題的後續步驟。

錯誤回覆變數類型將為任何。 您可以使用剖析值節點，將其轉換成 Power Fx 記錄。

屬性窗格也包含要求逾時屬性，該屬性接受以毫秒為單位的值。 預設值為 30 秒，但是您可以視需要變更此值。