다음을 통해 공유

정책 조각에 대한 변수 관리

적용 대상: 모든 API Management 계층

컨텍스트 변수를 사용하면 고급 파이프라인 시나리오에 대한 정책 조각 간의 데이터 공유를 사용할 수 있습니다. 적절한 변수 관리는 최적의 성능으로 신뢰할 수 있는 파이프라인을 빌드하는 데 중요합니다. 부적절한 처리로 인해 런타임 오류, 성능 문제 및 예측할 수 없는 동작이 발생할 수 있습니다.

변수 기본 사항

컨텍스트 변수는 정책 조각 간에 스레드로부터 안전한 데이터 공유를 제공하며 기본 제공 집합 변수 정책을 사용하여 생성됩니다. 각 요청은 자체 격리된 변수 컨텍스트를 유지 관리하여 동시 요청이 서로 간섭하지 않도록 합니다.

가변 수명 주기 관리

  • 요청 범위: 변수는 단일 요청 중에만 존재하며 요청이 완료되면 자동으로 가비지 컬렉션됩니다.

  • 단계 지속성: 인바운드 단계에서 설정된 변수는 동일한 요청 내에서 백 엔드, 아웃바운드 및 오류 단계에서 계속 사용할 수 있습니다.

  • 스레드 격리: 엄격한 스레드 격리는 각 요청이 자체 컨텍스트 개체를 사용하여 자체 스레드에서 실행되도록 하여 요청 간 데이터 간섭을 방지합니다.

  • 순차 업데이트: 모든 조각은 이전 값을 덮어쓰는 후속 조각과 함께 기존 변수를 수정할 수 있습니다. 순차적 실행은 잠금 메커니즘이 필요하지 않습니다.

  • 스토리지 임계값: 플랫폼은 작은 컬렉션(일반적으로 요청당 50개 이하의 변수)에 대한 컨텍스트 변수 관리를 최적화합니다.

조각에서 변수 설정 및 검색

<!-- Example: Set a request-id context variable that is a required value for other fragments -->
<set-variable name="request-id" value="@{
    var requestId = context.Request.Headers.GetValueOrDefault("X-Request-ID", "");
    if (string.IsNullOrEmpty(requestId)) {
        return Guid.NewGuid().ToString();
    }
    return requestId;
}" />

<!-- Example: Retrieve the same request-id context variable safely in another fragment -->
<set-header name="X-Correlation-ID" value="@{
    return context.Variables.GetValueOrDefault<string>("request-id", "unknown");
}" />

모범 사례

안전한 변수 액세스 사용

항상 잠재적인 null 값에 주의하고 안전한 액세스를 GetValueOrDefault사용하며 모든 변수 액세스에 의미 있는 기본값을 제공합니다.

<!-- Safe access with default value -->
<set-variable name="log-level" value="@{
    return context.Variables.GetValueOrDefault<string>("config-log-level", "INFO");
}" />

<!-- Safe string interpolation using GetValueOrDefault -->
<set-variable name="cache-key" value="@{
    var userId = context.Variables.GetValueOrDefault<string>("auth-user-id", "anon");
    var resource = context.Variables.GetValueOrDefault<string>("request-resource", "default");
    
    return $"cache:{userId}:{resource}";
}" />

변수 존재 확인

필수 구성 요소 조각에서 만든 변수가 액세스하기 전에 존재하는지 확인합니다. 종속성이 누락된 경우 다음 두 가지 전략 중에서 선택합니다.

전략 1: 페일 패스트(중요 종속성)

중요한 종속성이 누락된 경우 오류 응답을 반환합니다.

<choose>
    <when condition="@(!context.Variables.ContainsKey("user-id"))">
        <!-- Critical dependency missing - fail immediately -->
        <return-response>
            <set-status code="500" reason="Internal Server Error" />
            <set-body>{"error": "Required variable missing", "missing_dependency": "user-id"}</set-body>
        </return-response>
    </when>
    <otherwise>
        <!-- Safe to proceed - use the user-id variable -->
        <set-header name="X-User-ID" exists-action="override">
            <value>@(context.Variables.GetValueOrDefault<string>("user-id", ""))</value>
        </set-header>
    </otherwise>
</choose>

전략 2: 부드럽게 처리하기(옵션 종속성)

선택적 종속성이 누락된 경우 적절한 대체 동작으로 실행을 계속합니다.

<choose>
    <when condition="@(context.Variables.ContainsKey("user-id"))">
        <!-- Optional variable available - use it -->
        <set-header name="X-User-ID" exists-action="override">
            <value>@(context.Variables.GetValueOrDefault<string>("user-id", ""))</value>
        </set-header>
    </when>
    <otherwise>
        <!-- Fallback to default when variable unavailable -->
        <set-header name="X-User-ID" exists-action="override">
            <value>unknown</value>
        </set-header>
    </otherwise>
</choose>

변수 액세스 최소화

여러 액세스를 단일 식으로 통합하여 컨텍스트 변수 조회를 줄입니다.

<!-- Good: Single consolidated access -->
<set-variable name="log-entry" value="@{
    var level = context.Variables.GetValueOrDefault<string>("log-level", "INFO");
    var requestId = context.Variables.GetValueOrDefault<string>("request-id", "unknown");
    return $"[{level}] Request {requestId} completed";
}" />

<!-- Avoid: Multiple separate accesses -->
<set-variable name="level-prefix" value="@("[" + context.Variables.GetValueOrDefault<string>("log-level", "INFO") + "]")" />
<set-variable name="request-suffix" value="@("Request " + context.Variables.GetValueOrDefault<string>("request-id", "unknown") + " completed")" />
<set-variable name="log-entry" value="@(context.Variables.GetValueOrDefault<string>("level-prefix", "") + " " + context.Variables.GetValueOrDefault<string>("request-suffix", ""))" />

일관된 형식 유지 관리

최적의 성능 및 안정성을 위해 명시적 형식 처리를 사용합니다. 정책 식을 사용할 때는 연산자를 사용하여 예상 형식을 @() 지정합니다.

<!-- Set as boolean, use as boolean -->
<set-variable name="should-log-debug" value="@(true)" />
<choose>
    <when condition="@(context.Variables.GetValueOrDefault<bool>("should-log-debug", false))">
        <!-- Include detailed debug information in logs -->
    </when>
</choose>

관련 콘텐츠

  • Last updated on