查看整合項目的 OpenAPI 規格

預覽 — OpenAPI 規格

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

Application Integration 可動態產生並查看已發布整合項目的 OpenAPI 規格，這些整合項目已設定一或多個 API 觸發條件。存取整合項目的 OpenAPI 規格，即可：

• 全面瞭解整合的 API 端點、方法和資料結構。
• 提供整合 API 的詳細集中檢視畫面，有助於提高開發和疑難排解效率。
• 公開整合 API，並與對話式代理無縫整合，請參閱「使用 Application Integration 建構對話式代理」。

什麼是 OpenAPI 規格？

OpenAPI 規格 (OAS) 是標準的語言獨立格式，用於說明 RESTful API。OpenAPI 規格通常以 YAML 或 JSON 格式編寫，正式說明 API 元素，例如基本網址、路徑和動詞、標頭、查詢參數、內容類型、要求和回應模型等。如要進一步瞭解 OpenAPI 規格，請參閱 OpenAPI 規格。

注意：Application Integration 僅支援 OpenAPI 規格 3.0.1 版。

產生及查看 OpenAPI 規格

您可以在 Google Cloud 控制台的整合編輯器中，動態產生及查看整合項目的 OpenAPI 規格，也可以使用 API 呼叫。

事前準備

• 確認整合功能已設定一或多個 API 觸發條件。如要瞭解如何設定 API 觸發條件，請參閱「API 觸發條件」。
• 發布整合項目。如要瞭解如何發布整合項目，請參閱「測試及發布整合項目」。

查看 OpenAPI 規格

如要查看整合項目的 OpenAPI 規格，請選取下列任一選項：

控制台

如要查看特定整合的 OpenAPI 規格，請按照下列步驟操作：

1. 前往「Application Integration」(應用程式整合) 頁面。

   前往 Application Integration

2. 在導覽選單中，按一下「整合」。

   系統會顯示「整合」頁面，列出 Google Cloud 專案中所有可用的整合功能。

3. 按一下要查看 OpenAPI 規格的整合項目。系統會在整合編輯器中開啟整合服務。
4. 在整合編輯器工具列中，按一下「動作」選單 ，然後選取「查看 OpenAPI 規格」。

   「查看 OpenAPI 規格」窗格隨即顯示整合項目的 OpenAPI 規格。根據預設，產生的 OpenAPI 規格會包含整合中設定的所有 API 觸發程序。

   • 如要查看特定 API 觸發條件的 OpenAPI 規格，請從「API」下拉式清單中選取 API 觸發條件。
   • 如要將 OpenAPI 規格下載為 YAML 檔案，請按一下「下載」 。

注意：您一次只能透過整合編輯器，查看及下載單一整合項目的 OpenAPI 規格 (YAML 格式)。如要以 YAML 或 JSON 格式查看及下載 OpenAPI 規格，請按照「API」一節中的操作說明進行。

API

您可以使用 Application Integration API 的 generateOpenApiSpec 方法，透過 API 呼叫查看整合項目的 OpenAPI 規格。

使用下列 curl 指令，查看同一區域中一或多項整合的 OpenAPI 規格：

提示：Linux 和 macOS 作業系統通常會預先安裝 curl。如果尚未安裝 curl，可以前往 curl 版本與下載頁面下載這項工具。

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec"
          

請替換下列項目：

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n：整合項目中 API 觸發條件的名稱，您想查看這些觸發條件的 OpenAPI 規格。
• INTEGRATION_NAME：整合名稱。
• DOC_TYPE：要生成的文件類型。支援的值為 YAML 或 JSON。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• LOCATION：您 Google Cloud 專案的位置。
  注意：您只能查看同一區域中多個整合項目的 OpenAPI 規範。

瞭解 OpenAPI 規格

Application Integration 會按照 OpenAPI 規格 3.0 標準，為已發布的整合項目產生 OpenAPI 規格。下表說明 Application Integration 中產生的 OpenAPI 規格元素：

元素	說明
openapi	使用的 OpenAPI 規格版本。
info	整合項目的相關資訊，例如名稱 (標題)、說明和已發布版本。
servers	代管整合的伺服器網址。
paths	系統會為整合服務中選取的每個 API 觸發條件建立路徑。伺服器網址和路徑會構成 API 端點，用於發出 API 呼叫。 系統會根據為對應 API 觸發程序設定的輸入和輸出變數，填入 Request 和 Response 欄位。 注意：Application Integration 目前僅支援一組有限的 JSON 結構定義關鍵字。如要瞭解支援的關鍵字，請參閱注意事項。
components	schemas 欄位包含 API 觸發條件輸入和輸出變數的 JSON 結構定義。 securitySchemes 欄位包含 API 觸發程序的驗證資訊。

注意事項

查看整合的 OpenAPI 規格時，請注意下列事項：

• 只有已發布的整合服務才會產生 OpenAPI 規格。
• 只有設定一或多個 API 觸發條件的整合項目，才會產生 OpenAPI 規格。
• OpenAPI 規格只會為相同區域的整合項目產生。
• OpenAPI 規格預設會以 YAML 格式產生。如要以 JSON 格式產生及查看 OpenAPI 規格，請在 API 呼叫中將 fileFormat 參數設為 JSON。
• Application Integration 目前僅支援下列有限的 JSON 結構定義關鍵字：
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• 使用 Swagger 編輯器驗證 OpenAPI 規格時，您可能會遇到與 API 路徑相關的語意錯誤，類似下圖：

  

  您可以放心忽略這些錯誤。OpenAPI 規範仍有效。

後續步驟

• 使用 Application Integration 建構對話式代理。
• 瞭解 API 觸發條件。
• 瞭解如何測試及發布整合項目。