使用版本控制來發展您的 API

發行項
06/23/2023

Azure Logic Apps 的自訂連接器、Microsoft Power Automate 或 Microsoft Power Apps 必須提供 OpenAPI 規格檔案。此 OpenAPI 規格會定義稱為作業的個別進入點。每項作業都有唯一的 operationId，和唯一的 urlPath 和 HttpVerb 組合。

{
    "/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        },
        "post": {
            "summary": "Insert row",
            "description": "This operation inserts an item.",
            "operationId": "PostItem"
        }
    }
}

這些作業可能會隨著功能的新增或擴充而成長和變更。有些變更只是附加的，不一定會中斷用戶端與伺服器之間存在的合約。新增新的參數、傳回更多資料，或允許更具彈性的輸入可能會落在此類別中。

不過，許多變更實際上可能會中斷 OpenAPI 規格中所述的合約。移除參數、不再支援特定輸入，或變更輸入、輸出或作業本身的意義和行為，也會落在「重大變更」類別中。

為了安全地發展 API，請務必遵循可由用戶端瀏覽的模式。 API 必須負責維護回溯相容性、通訊意圖，以及描繪版本設定屬性。用戶端必須負責顯示或隱藏已取代、已過期或可能有較新版本的作業。如此一來，作業就可以隨著時間成長和開發，而不會讓依賴它們的應用程式過度脆弱。

API 註釋

OpenAPI 沒有作業版本設定的內建支援。若要完成我們的目標，大部分的工作都是透過 x-ms-api-annotation 物件來完成，這個物件同時在全域範圍和作業範圍套用。全域物件包含適用於整個 API 的屬性：

{
    "x-ms-api-annotation": {
        "status": "Preview"
    }
}

屬性	數值	預設	描述
狀態	`"Preview"` `"Production"`	`"Preview"`	整體 API 的狀態—從預覽開始，並隨著使用量和穩定性而升級至生產環境

在作業範圍中，此物件包含更詳細的屬性。物件之外還有其他屬性，可套用並參與版本設定進化程序：

{
    "deprecated": true,
    "x-ms-api-annotation": {
        "status": "Production",
        "family": "MyOperation",
        "revision": 2
    }
}

屬性	數值	預設值	描述
已取代	`null` `false` `true`	`false`	指出作業是否已被取代
x-ms-visibility	`null` `""` `"Important"` `"Advanced"` `"Internal"`	`""`	這項作業的預期可見度和重要性，其中 `null` 或 `""` 意指正常狀態
狀態	`"Preview"` `"Production"`	`"Production"`	作業的狀態—這可能與 API 本身的狀態不同，但是如果未指定，則會繼承自最上層 API 狀態
系列	{一般作業名稱}	operationName	套用至這項作業之每個修訂的名稱
修訂	numeric (1,2,3...)	`1`	指定作業系列的修訂
到期	ISO8601 日期	(無)	選擇性的用戶端提示，表示預計的支援結束

如果用戶端不再需要使用此作業時，已取代可設定為 true。這個屬性存在於 OpenAPI 固定欄位規格中。

可見度是作業的預定相對重要性指標。 "Important" 可見度表示作業應該朝清單頂端，以醒目方式顯示。一般可見度 (以 null 或空字串 "" 表示) 是預設值，表示作業會出現在清單中，可能是在重要作業之後。 "Advanced" 可見度表示作業可能朝向清單底部，或甚至一開始是隱藏在 expando 控制項後方。進階作業可能會更難使用、較不受歡迎，或者適用範圍較狹窄。 "Internal" 可見度表示不應對使用者公開作業，而且應該只在內部使用。內部作業在程式設計方式上實用且有價值，但不適用於使用者。內部作業也可能這樣標示，以便在取代程序期間將它們從任何 UI 排序中隱藏，而不需要實際將它們從 API 中移除，否則會導致中斷性變更。

狀態表示 API 或作業的穩定性。 "Preview" 表示作業或 API 是新的，而且可能是未經驗證。預覽是一項指標，指出生產系統對於假設相依性應該謹慎。一旦作業或 API 變得更好，而且證明它符合可靠性、成功率和擴充性的標準，就可以刻意升級為 "Production" 狀態。

下列計量需求通常適用於尋求 "Production" 狀態的作業：

3 週期間 80% 成功率
- 定義為 2xx 範圍中的 HTTP 回應碼百分比
3 週期間 99.9% 持續可靠性
- 定義為非 5xx 範圍中的 HTTP 回應碼百分比 (502、504和 520 會從這個計算中排除)

系列表示作業之間的關聯性，這些作業概念上相同，但是是不同的修訂，其間可能會有中斷性變更。如果多個作業應該被視為彼此的修訂，則會共用相同的系列名稱，並依其唯一的修訂編號排序。

修訂表示作業系列內作業的發展順序。系列內的每個作業都有一個修訂，這是意指順序的整數索引。空的修訂將會視為修訂 1。當有較新版本的作業可供使用時，用戶端應該更醒目地顯示它們，並以更刻意的方式加以建議，但是仍然允許選取尚未取代的可能舊版修訂。

過期是選擇性的，表示不再保證支援作業的潛在結束期限。這應該只針對已取代的作業設定，而且目前不會反映在任何介面中。

作業存留期

作業具有可預測的存留期，如範例所示。

起點

一開始，作業可能不一定會指出修訂的任何內容。這些作業會套用預設值，因此會在與 operationId 相等的系列名稱中視為修訂 1。

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        }
    }
}

這相當於更明確的定義：

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
}

作業起始

API 的大部分發展會構成作業的新增。例如，新方法和現有方法的新修訂。為了安全地起始新的修訂，您以這種方式調整 OpenAPI 規格：

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (V1 - downplayed)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-visibility": "advanced",
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows (V2 - new hotness)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Preview",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

重要

請注意，GetItems V2 有一個唯一的 operationId，而且一開始會以預覽狀態列出。另請注意，GetItems v1 現已具備進階可見度，因此不會以醒目方式顯示。

作業取代

有時候，如果現有 V1 進入點持續提供價值，而且沒有任何令人信服的理由要將它取代，則會無限期保留。不過，許多 V2 進入點會刻意取代 V1 進入點。為了安全地執行這項操作，與原始作業的所有流量應該在名義上達到零。一旦遙測確認這種情況，就可以進行下列變更：

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (deprecated)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": true,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

重要

請注意，GetItems V1 現在已標示為已取代。這是取代作業的最終轉換。 GetItems V2 現已完全取代 GetItems V1。

為何要這麼麻煩？

遵循作業版本設定有許多原因。這主要是為了確保當使用者將連接器作業整合到其資料流程時，例如 Azure Logic Apps 和 Power Automate 等的用戶端會繼續正常運作。每當發生下列情形時，都應該使用上述方法來進行作業的版本設定：

新增作業的新修訂
現有作業新增或移除參數
現有作業大幅變更輸入或輸出

嚴格來說

在某些情況下，您可能不需要進行版本設定—但是在這麼做時您應該非常小心，並執行大量測試，以確保您不會忽略使用者可能意外中斷的邊緣案例。以下是當您不需要執行時才會出現的謹慎簡短清單：

新增了作業。

這不會特別中斷現有的用戶端。
新的選擇性參數已新增至現有的作業。

這不會中斷現有的呼叫，但必須謹慎考慮。
現有的作業稍微改變行為。

根據變更的本質以及使用者所依賴的內容，可能不會中斷現有的呼叫端。這是最不穩定的情形之一，因為輸入接受、輸出產生、計時或處理的大幅差異可能會影響作業的行為，而這可能會讓您難以確定變更的風險。

當您進行任何非不重要 API 變更時，一律會建議您小心，並逐一查看修訂。

提供意見反應

非常感謝您提供有關連接器平台問題，或新功能構想的意見反應。若要提供意見反應，請移至提交問題或取得連接器說明，然後選取您的意見反應類型。