MonetizationLimitsCheck 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

참고: MonetizationLimitsCheck 정책은 조직에서 Apigee 수익 창출을 사용 설정한 경우에만 유효합니다.

개요

MonetizationLimitsCheck 정책을 사용하면 수익 창출 한도를 적용할 수 있습니다.

특히 수익 창출 API에 액세스하는 앱 개발자가 관련 API 제품에 대한 구독을 구매하지 않은 경우 또는 개발자에게 잔액이 부족한 경우 정책이 트리거됩니다. 이 경우 MonetizationLimitsCheck 정책은 결함을 유발하고 API 호출을 차단합니다. 자세한 내용은 API 제품에 개발자 구독 적용을 참조하세요.

mint 흐름 변수 참조에 설명된 대로 API 프록시에 MonetizationLimitsCheck 정책을 연결하면 mint.limitscheck.* 및 mint.subscription_* 흐름 변수가 채워집니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

참고: MonetizationLimitsCheck 정책을 사용하더라도 유료 개발자가 API 호출을 과도하게 수행하여 결국 개발자의 전자 지갑 잔액이 부족해질 수 있습니다. 개발자의 잔액이 부족해지는 상황들을 이해하기 위해서는 개발자 잔액 부족을 참조하세요.

<MonetizationLimitsCheck>

MonetizationLimitsCheck 정책을 정의합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	해당 사항 없음
하위 요소	<DisplayName> <FaultResponse> <IgnoreUnresolvedVariables>

다음 표에서는 <MonetizationLimitsCheck>의 하위 요소를 간략하게 설명합니다.

하위 요소	필수 여부	설명
<DisplayName>	선택사항	정책의 커스텀 이름입니다.
<FaultResponse>	선택사항	요청 클라이언트로 반환되는 응답 메시지를 정의합니다.
<IgnoreUnresolvedVariables>	선택사항	흐름에서 확인되지 않은 변수 오류를 무시합니다.

<MonetizationLimitsCheck> 요소는 다음 구문을 사용합니다.

문법

<?xml version="1.0" encoding="UTF-8" standalone="no"?><MonetizationLimitsCheck continueOnError="[true|false]" enabled="[true|false]" name="policy_name">
   <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
   <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
       </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>VALUE</IgnoreUnresolvedVariables>
</MonetizationLimitsCheck>

예시

다음 예시에서 개발자가 연관된 API 제품 구독을 구입하지 않은 경우에는 수익 창출 API 액세스가 차단되고 커스텀 메시지와 함께 403 상태가 반환됩니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MonetizationLimitsCheck continueOnError="false" enabled="true" name="MonetizationLimitsCheck-1">
  <DisplayName>Monetization-Limits-Check-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType="text/xml">
        <error>
          <messages>
            <message>Usage has been exceeded ({mint.limitscheck.isRequestBlocked}) or app developer has been suspended</message>
          </messages>
        </error>
      </Payload>
      <StatusCode>403</StatusCode>
    </Set>
  </FaultResponse>
</MonetizationLimitsCheck>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성	기본	필수 여부	설명
name	해당 없음	필수	정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
continueOnError	false	선택	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조: 오류 규칙이 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 정책 오류 처리
enabled	true	선택	정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async	false	지원 중단됨	이 속성은 지원이 중단되었습니다.

하위 요소 참조

이 섹션에서는 <MonetizationLimitsCheck>의 하위 요소를 설명합니다.

<DisplayName>

name 속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값	해당 사항 없음
필수 여부	선택사항. <DisplayName>을 생략하면 정책의 name 속성 값이 사용됩니다.
유형	문자열
상위 요소	<PolicyElement>
하위 요소	없음

<DisplayName> 요소는 다음 구문을 사용합니다.

구문

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

예시

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

<FaultResponse>

요청 클라이언트로 반환되는 응답 메시지를 정의합니다. FaultResponse는 RaiseFault 정책의 <FaultResponse> 요소와 동일한 설정을 사용합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<MonetizationLimitsCheck>
하위 요소	<AssignVariable> <Add> <Copy> <Remove> <Set>

<AssignVariable>

대상 흐름 변수에 값을 할당합니다. 흐름 변수가 없으면 AssignVariable이 변수를 만듭니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<FaultResponse>
하위 요소	<Name> <Value>

예를 들어 다음 코드를 사용하여 MonetizationLimitsCheck 정책에서 myFaultVar이라는 변수를 설정합니다.

<FaultResponse>
<AssignVariable>
  <Name>myFaultVar</Name>
  <Value>42</Value>
</AssignVariable>
</FaultResponse>

그러면 오류 규칙의 정책이 변수에 액세스할 수 있습니다. 예를 들어 다음 AssignMessage 정책은 변수를 사용하여 오류 응답에 헤더를 설정합니다.

<AssignMessage enabled="true" name="Assign-Message-1">
<Add>
  <Headers>
    <Header name="newvar">{myFaultVar}</Header>
  </Headers>
</Add>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

MonetizationLimitsCheck 정책의 <AssignVariable>은 AssignMessage 정책의 <AssignVariable> 요소와 동일한 구문을 사용합니다.

<Name>

변수 이름입니다. 자세한 내용은 AssignMessage 정책의 이름 요소를 참조하세요.

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	<AssignVariable>
하위 요소	없음

<Value>

변수 값입니다. 자세한 내용은 AssignMessage 정책의 값 요소를 참조하세요.

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	<AssignVariable>
하위 요소	없음

<Add>

HTTP 헤더를 오류 메시지에 추가합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<FaultResponse>
하위 요소	<Headers>

<Headers>

추가, 설정, 복사, 삭제할 HTTP 헤더를 지정합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<Add> <Copy> <Remove> <Set>
하위 요소	없음

• 빈 헤더(<Add><Headers/></Add>)는 헤더를 추가하지 않습니다.
• <Header> 요소는 메시지 템플릿이라는 동적 문자열 대체 기능을 지원합니다.

예를 들면 다음과 같습니다.

헤더 추가

다음 예시에서는 request.user.agent 흐름 변수의 값을 헤더에 복사합니다.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

헤더 설정

다음 예시에서는 user-agent 헤더를 <AssignTo> 요소로 지정된 메시지 변수로 설정합니다.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

헤더 복사 - 1

다음 예시에서는 요청에서 headerA를 복사합니다.

<Copy source='request'>
    <Headers>
        <Header name="headerA"/>
    </Headers>
</Copy>

헤더 복사 - 2

다음 예시에서는 여러 헤더를 복사합니다.

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

이 예시에서는 'h1', 'h2', 'h3'의 두 번째 값을 복사합니다. 'h3'에 값이 하나만 있으면 'h3'이 복사되지 않습니다.

헤더 삭제 - 1

다음 예시에서는 헤더를 삭제합니다.

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

헤더 삭제 - 2

다음 예시에서는 여러 헤더를 삭제합니다.

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

이 예시에서는 'h1', 'h2'와 'h3'의 두 번째 값을 삭제합니다. 'h3'에 값이 하나만 있으면 'h3'이 삭제되지 않습니다.

<Copy>

source 속성으로 지정된 메시지에서 부터 오류 메시지로 정보를 복사합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<FaultResponse>
하위 요소	<Headers> <StatusCode>

다음 표는 <Copy>의 속성을 설명합니다.

속성	필수 여부	유형	설명
source	선택사항	문자열	사본의 소스 객체를 지정합니다. 소스를 지정하지 않으면 단순 메시지로 취급됩니다. 예를 들어 정책이 요청 흐름에 있는 경우 소스가 기본적으로 요청 객체로 지정됩니다. 정책이 응답 흐름에 있으면 기본적으로 응답 객체로 지정됩니다. 소스를 생략하면 흐름 변수에 대한 절대 참조를 복사본의 소스로 사용할 수 있습니다. 예를 들어 값을 {request.header.user-agent}로 지정합니다. 소스 변수를 확인할 수 없거나 메시지 외의 유형으로 확인되면 <Copy>가 응답하지 않습니다.

<StatusCode>

오류 메시지에 HTTP 상태 코드를 지정합니다. source 속성으로 지정된 객체에 대해 값을 복사하거나 설정할 수 있습니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<Copy> <Set>
하위 요소	없음

예를 들면 다음과 같습니다.

상태 코드 복사

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

상태 코드 설정

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

<Remove>

오류 메시지에서 지정된 HTTP 헤더를 삭제합니다. 모든 헤더를 삭제하려면 <Remove><Headers/></Remove>를 지정합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<FaultResponse>
하위 요소	<Headers>

<Set>

오류 메시지에 정보를 설정합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	복합 유형
상위 요소	<FaultResponse>
하위 요소	<Headers> <Payload> <StatusCode>

<Payload>

오류 메시지의 페이로드를 설정합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	<Set>
하위 요소	없음

예를 들면 다음과 같습니다.

텍스트 페이로드 설정

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

JSON 페이로드 설정 - 1

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

JSON 페이로드 설정 - 2

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

이 예시에서는 구분 기호 문자와 함께 variablePrefix 및 variableSuffix 속성을 사용하여 변수를 삽입합니다.

JSON 페이로드 설정 - 3

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

이 예시에서는 중괄호를 사용하여 변수를 삽입합니다. 16.08.17 출시 버전부터 시작해서 중괄호를 사용할 수 있습니다.

XML 페이로드 설정

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

이 예시에서는 중괄호를 사용하여 변수를 삽입합니다. 16.08.17 출시 버전부터 시작해서 중괄호를 사용할 수 있습니다.

<IgnoreUnresolvedVariables>

해결되지 않은 변수가 발생하면 처리를 중지할지 여부를 결정합니다.

확인되지 않은 변수를 무시하고 계속 처리하려면 true로 설정합니다. 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.

<IgnoreUnresolvedVariables>를 true로 설정하는 것은 <MonetizationLimitsCheck>의 continueOnError를 true로 설정하는 것과 다릅니다. continueOnError를 true로 설정하면 Apigee가 모든 오류를 무시하지만 변수의 오류를 무시하지 않습니다.

<IgnoreUnresolvedVariables> 요소는 다음 문법을 사용합니다.

문법

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

예시

다음 예시에서는 <IgnoreUnresolvedVariables>를 false로 설정합니다.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

오류 코드

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	원인
mint.service.subscription_not_found_for_developer	500	이 오류는 개발자에게 API 제품 구독이 없을 때 발생합니다.
mint.service.wallet_not_found_for_developer	500	이 오류는 선불 개발자가 요금제에 지정된 통화를 전자 지갑에 포함하지 않고 수익 창출 API를 사용하려고 시도할 때 발생합니다.
mint.service.developer_usage_exceeds_balance	500	이 오류는 선불 개발자의 사용량이 전자 지갑 잔액을 초과할 때 발생합니다.
mint.service.wallet_blocked_due_to_inactivity	500	이 오류는 선불 개발자의 전자 지갑이 1.5년 이상 충전되지 않았고 개발자가 API를 사용하려고 시도할 때 발생합니다.

오류 변수

정책에 실행 오류가 발생할 때마다 Apigee는 오류 메시지를 생성합니다. 오류 응답에서 이러한 오류 메시지를 볼 수 있습니다. 시스템에서 생성된 오류 메시지가 제품의 컨텍스트와 관련이 없을 경우가 많습니다. 메시지를 보다 의미 있게 만들기 위해 오류 유형에 따라 오류 메시지를 맞춤설정할 수 있습니다.

오류 메시지를 맞춤설정하려면 오류 규칙 또는 RaiseFault 정책을 사용하면 됩니다. 오류 규칙과 RaiseFault 정책의 차이점에 대한 자세한 내용은 FaultRules와 RaiseFault 정책 비교를 참조하세요. 오류 규칙과 RaiseFault 정책 모두에서 Condition 요소를 사용하여 조건을 확인해야 합니다. Apigee는 각 정책에 고유한 오류 변수를 제공하며 정책이 런타임 오류를 트리거할 때 오류 변수 값이 설정됩니다. 이러한 변수를 사용하여 특정 오류 조건을 확인하고 적절한 조치를 취할 수 있습니다. 오류 조건 확인에 대한 자세한 내용은 빌드 조건을 참조하세요.

변수	각 항목의 의미는 다음과 같습니다.	예
fault.name	fault.name은 런타임 오류 표에 나열된 오류 중 하나와 일치할 수 있습니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name Matches "UnresolvedVariable"
MonetizationLimitsCheck.POLICY_NAME.failed	POLICY_NAME은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	MonetizationLimitsCheck.monetization-limits-check-1.failed = true

정책 오류에 대한 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

흐름 변수

MonetizationLimitsCheck 정책이 실행되면 다음과 같은 사전 정의된 흐름 변수가 자동으로 채워집니다. 자세한 내용은 mint 흐름 변수를 참조하세요.

흐름 변수	설명
mint.limitscheck.is_request_blocked	true: 차단된 요청의 경우
mint.limitscheck.is_subscription_found	true: API 구독이 있는 경우
mint.limitscheck.purchased_product_name	구매한 API 제품의 이름입니다. 예를 들면 MyProduct입니다.
mint.limitscheck.status_message	상태 메시지입니다. 예를 들면 limits_check_success입니다.
mint.subscription_end_time_ms	API 제품 구독의 종료 시간입니다.
mint.subscription_start_time_ms	API 제품 구독의 시작 시간입니다. 예를 들면 1618433956209입니다.