將 SAP OData 中繼資料匯入為 API

適用於：所有 APIM 層

本文說明如何使用中繼資料描述來匯入 OData 服務。 在本文中，以 SAP Gateway Foundation 為例。

在本文中，您將：

• 從 SAP 服務擷取 OData 中繼資料
• 將 OData 中繼資料直接匯入到 APIM，或轉換成 OpenAPI 規格之後匯入
• 完成 API 設定
• 在 Azure 入口網站中測試 API

必要條件

• 現有的 API 管理執行個體。 如果尚無執行個體，請建立。

• 以 OData v2 或 v4 公開的 SAP 系統和服務。

• 如果 SAP 後端使用自我簽署憑證 (測試用途)，您可能需要停止驗證 SSL 的信任鏈結。 作法是在 API 管理執行個體中設定後端：

  1. 在 Azure 入口網站的 [API] 下，選取 [後端]>[+ 新增]。
  2. 新增 [自訂 URL] 來指向 SAP 後端服務。
  3. 取消核取 [驗證憑證鏈結] 和 [驗證憑證名稱]。

  注意

  在生產情節中，使用適當的憑證進行端對端 SSL 驗證。

從 SAP 服務擷取 OData 中繼資料

使用下列其中一種方法，從 SAP 服務擷取中繼資料 XML。 如果您打算將中繼資料 XML 轉換成 OpenAPI 規格，請在本機儲存檔案。

• 使用 SAP 閘道用戶端 (交易 /IWFND/GW_CLIENT)，或
• 進行直接 HTTP 呼叫以擷取 XML：http://<OData server URL>:<port>/<path>/$metadata

移至您的 API 管理執行個體

1. 在 Azure 入口網站中，搜尋並選取 [API 管理服務]。

   

2. 在 [API 管理服務] 頁面中，選取您的 API 管理執行個體。

   

將 API 匯入 APIM

選擇下列其中一種方法，將 API 匯入 APIM：直接將中繼資料 XML 匯入為 OData API，或將中繼資料 XML 轉換成 OpenAPI 規格。

OData 中繼資料

匯入 OData 中繼資料

1. 在左側功能表中，選取 [API] > [+ 新增 API]。

2. 在 [從定義建立] 下，選取 [OData]。

   

3. 輸入 API 設定。 您稍後可以移至 API 的 [設定] 索引標籤來更新設定。

   1. 在 [OData 規格] 中，輸入 OData 中繼資料端點的 URL，通常是服務根目錄的 URL，後面再附上 /$metadata。 或者，選取要匯入的本機 OData XML 檔案。

   2. 輸入其餘設定來設定您的 API。 這些設定會在匯入和發佈您的第一個 API 教學課程中說明。

4. 選取 建立。

   API 會新增至 [API] 清單。 OData 中繼資料描述中公開的實體集和函式，會顯示在 API 的 [實體集和函式] 索引標籤上。

   

更新 OData 結構描述

您可以在入口網站中存取編輯器，以檢視 API 的 OData 結構描述。 如果 API 變更，您也可以從檔案或 OData 服務端點更新 APIM 中的結構描述。

1. 在入口網站中，瀏覽至您的 API 管理執行個體。

2. 在左側功能表中，選取 [API]>[您的 OData API]。

3. 在 [實體集和函式] 索引標籤上，選取實體集或函式旁邊的捷徑功能表 (...)，然後選取 [編輯]。

   

4. 檢閱結構描述。 若要更新，請選取 [從檔案更新] 或 [從端點更新結構描述]。

   

測試 OData API

1. 在左側功能表中，選取 [API]>[您的 OData API]。

2. 在 [實體集和函式] 索引標籤上，選取實體集或函式旁邊的捷徑功能表 (...)，然後選取 [測試]。

   

3. 在測試主控台，輸入測試的範本參數、查詢參數和標頭，然後選取 [測試]。 深入了解如何在入口網站中測試 API。

保護 OData API

透過套用現有的驗證和授權原則和 OData 驗證原則來保護您的 OData API，以防止透過 OData API 要求進行攻擊。

提示

在入口網站中，於 [API 原則] 索引標籤上設定 OData API 的原則。

OpenAPI 規格

將 OData 中繼資料轉換為 OpenAPI JSON

1. 將 OData XML 轉換為 OpenAPI JSON 格式。 視中繼資料 XML 而定，使用 OData v2 或 OData v4 的 OASIS 開放原始碼工具。

   下列範例命令轉換測試服務 epm_ref_apps_prod_man_srv 的 OData v2 XML：

   odata-openapi -p --basePath '/sap/opu/odata/sap/epm_ref_apps_prod_man_srv' \
    --scheme https --host <your IP address>:<your SSL port> \
    ./epm_ref_apps_prod_man_srv.xml
   

   注意

   • 若要以單一 XML 檔案做測試，您可以使用以開放原始碼工具為基礎的 Web 型轉換器。
   • 使用工具或 Web 型轉換器時，可選擇指定 SAP OData 伺服器的 <IP 位址>:<連接埠>。 或者，稍後在產生的 OpenAPI 規格中，或在匯入至 API 管理之後，新增此資訊。

2. 將 openapi-spec.json 檔案儲存在本機，以匯入至 API 管理。

匯入和發佈後端 API

1. 從側邊導覽功能表的 [API] 區段下，選取 [API]。

2. 在 [建立新的定義] 下，選取 [OpenAPI 規格]。

   

3. 按一下 [選取檔案]，然後選取您在上一個步驟中儲存在本機的 openapi-spec.json 檔案。

4. 輸入 API 設定。 您可以在建立期間設定這些值，或稍後前往 [設定] 索引標籤來進行設定。

   • 在 [API URL 尾碼] 中，建議使用與原始 SAP 服務中相同的 URL 路徑。

   • 如需 API 設定的詳細資訊，請參閱匯入和發佈您的第一個 API 教學課程。

5. 選取 建立。

注意

API 匯入限制記載於另一篇文章。

完成 API 設定

將下列三個作業新增至您匯入的 API。

• GET /$metadata

  作業	描述	作業的進一步設定
  GET /$metadata	讓 API 管理連接 $metadata 端點，用戶端與 OData 伺服器整合需要此端點。 您產生和匯入的 OpenAPI 規格未包含此必要作業。	新增 200 OK 回應。

  

• HEAD /

  作業	描述	作業的進一步設定
  HEAD /	讓用戶端在必要時與 SAP 伺服器交換跨網站偽造要求 (CSRF) 權杖。 SAP 也允許使用 GET 動詞來交換 CSRF 權杖。 本文未涵蓋 CSRF 權杖交換。 請參閱代理權杖交換的 API 管理原則程式碼片段範例。	N/A

  

• GET /

  作業	描述	作業的進一步設定
  GET /	在服務根目錄啟用原則組態。	設定下列輸入 rewrite-uri 原則，在轉送至服務根目錄的要求尾端附加斜線： <rewrite-uri template="/" copy-unmatched-params="true" /> 無論要求有無尾端斜線 (有些後端會認為不同)，此原則消除可能的模糊性。

  

此外，使用適合環境的方法來設定向後端驗證。 如需範例，請參閱 APIM 驗證和授權原則。

測試您的 API

1. 瀏覽至 API 管理執行個體。

2. 從側邊導覽功能表的 [API] 區段下，選取 [API]。

3. 在 [所有 API] 下，選取您匯入的 API。

4. 選取 [測試] 索引標籤以存取測試主控台。

5. 選取作業，輸入任何必要值，然後選取 [傳送]。

   例如，測試 GET /$metadata 呼叫，以確認對 SAP 後端的連線能力

6. 檢視回應。 若要進行疑難排解，請追蹤 呼叫。

7. 測試完成時，結束測試主控台。

生產考量

• 請參閱整合 API 管理與 SAP 閘道的端對端情節範例。
• 使用 API 管理原則來控制對 SAP 後端的存取。 例如，如果 API 匯入為 OData API，請使用驗證 OData 要求原則。 另請參閱 SAP 主體傳播和擷取 X-CSRF 權杖的原則程式碼片段。
• 關於大規模部署、管理和遷移 API 的指導，請參閱：
  • 使用 APIOps 來自動部署 API
  • 在 API 管理中使用 Azure Resource Manager 範本來支援 CI/CD。

相關主題

• API 匯入限制
• 匯入 OpenAPI 規格
• 匯入 SOAP API
• 匯入 SOAP API 並轉換為 REST
• 匯入 App Service API
• 匯入容器應用程式 API
• 匯入 WebSocket API
• 匯入 GraphQL API
• 匯入 GraphQL 結構描述並設定欄位解析器
• 匯入 Azure 函式應用程式
• 匯入 Azure 邏輯應用程式
• 匯入 Service Fabric 服務
• 匯入 Azure OpenAI API
• 匯入 OData API
• 匯入 SAP OData 中繼資料
• 匯入 gRPC API
• 編輯 API