버전 제어를 사용하여 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의 전체 상태—Preview(미리 보기)에서 시작하여 사용량 및 안정성 지시에 따라 Production(프로덕션)으로 에스컬레이션

작업 범위에서 이 개체에는 더 자세한 속성이 포함됩니다. 또한 버전 관리 진화 프로세스에 적용하고 참여하는 개체 외부의 추가 속성도 있습니다.

{
    "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	이 작업의 모든 수정 버전에 적용되는 이름입니다.
개정	숫자(1,2,3...)	`1`	지정된 작업 패밀리의 수정 버전입니다.
만료	ISO8601 날짜	(없음)	예상 지원 종료를 나타내는 클라이언트에 대한 선택적 힌트입니다.

클라이언트에서 이 작업을 더 이상 사용하지 않는 경우 deprecated(사용되지 않음)를 true로 설정할 수 있습니다. 이 속성은 OpenAPI 고정 필드 사양에 있습니다.

visibility(표시 유형)는 작업의 의도된 상대적 우월성에 대한 지표입니다. "Important" 표시 유형은 작업이 눈에 띄게 표시되도록 목록의 위쪽에 있어야 함을 나타냅니다. 일반 표시 유형(null 또는 빈 문자열인 ""로 표시됨)이 기본값이며, 중요한 작업 이후에 작업이 목록에 표시된다는 것을 나타냅니다. "Advanced" 표시 유형은 작업이 목록의 아래쪽에 있거나 처음에는 expando 컨트롤 뒤에 숨겨져 있음을 나타냅니다. Advanced(고급) 작업은 사용하기가 더 어렵거나, 자주 사용되지 않거나, 더 구체적으로 적용할 수 있습니다. "Internal" 표시 유형은 작업이 사용자에게 공개되지 않아야 하며 내부에서만 사용되어야 함을 나타냅니다. Internal(내부) 작업은 프로그래밍 방식으로 유용하고 중요하지만 최종 사용자를 위한 것이 아닙니다. 또한 Internal 작업은 API에서 실제로 제거하지 않고 사용되지 않는 프로세스 중에 어떤 종류의 UI에서 숨기기 위해 이처럼 표시될 수 있으며, 그렇지 않으면 호환성이 손상되는 변경이 발생할 수 있습니다.

상태는 API 또는 작업의 안정성을 나타냅니다. "Preview"는 작업 또는 API가 새롭고 잠재적으로 입증되지 않았음을 나타냅니다. Preview는 프로덕션 시스템에서 종속성 가정에 대해 신중해야 함을 나타내는 지표입니다. 작업 또는 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가 있으며 처음에는 Preview 상태로 나열됩니다. 또한 GetItems V1은 이제 Advanced 표시 유형을 사용하므로 눈에 띄게 표시되지 않습니다.

작업 사용 중단

경우에 따라 기존 V1 진입점에서 가치를 계속 제공하고 만료되어야 하는 설득력 있는 이유가 없으면 이러한 진입점을 무기한으로 유지합니다. 그러나 많은 V2 진입점이 의도적으로 V1 진입점을 대체합니다. 이를 안전하게 수행하려면 모든 트래픽이 원래 작업에 대해 명목상 0에 도달해야 합니다. 원격 분석에서 이러한 상황이 확인되면 다음과 같이 변경할 수 있습니다.

{
    "/{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를 변경하는 경우 매우 주의하여 수행하고 수정을 반복하는 것이 좋습니다.

피드백 제공

커넥터 플랫폼 관련 문제 또는 새로운 기능 아이디어에 대한 피드백을 주셔서 정말 감사합니다. 피드백을 제공하려면 문제 제출 또는 커넥터 관련 도움말 보기로 이동하여 피드백 유형을 선택하십시오.