Política MonetizationLimitsCheck

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Nota: La política MonetizaciónLimitsCheck solo es válida si habilitaste la monetización de Apigee en tu organización.

Descripción general

La política MonetizationLimitsCheck te permite aplicar límites de monetización.

En particular, la política se activa si el desarrollador de apps que accede a la API monetizada no ha comprado una suscripción al producto de API asociado o si el desarrollador no tiene saldo suficiente. En este caso, la política MonetizationLimitsCheck generará una falla y bloqueará una llamada a la API. Para obtener más información, consulta Aplica suscripciones de desarrollador a productos de API.

Cuando adjuntas la política MonetizationLimitsCheck a un proxy de API, las variables de flujo mint.limitscheck.* y mint.subscription_* se propagan, como se describe en la referencia de la variable de flujo mint.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Nota: A pesar de usar la política MonetizationLimitsCheck, es posible que un desarrollador prepago pueda realizar llamadas excesivas a la API y que termine con un saldo negativo. Para comprender las condiciones en las que el saldo de un desarrollador se vuelve negativo, consulta Saldo negativo de desarrollador.

<MonetizationLimitsCheck>

Define la política MonetizationLimitsCheck.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	N/A
Elementos secundarios	<DisplayName> <FaultResponse> <IgnoreUnresolvedVariables>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <MonetizationLimitsCheck>.

Elemento secundario	¿Es obligatorio?	Descripción
<DisplayName>	Opcional	Un nombre personalizado para la política
<FaultResponse>	Opcional	Define el mensaje de respuesta que se muestra al cliente solicitante.
<IgnoreUnresolvedVariables>	Opcional	Ignora cualquier error de variable no resuelto en el flujo.

El elemento <MonetizationLimitsCheck> usa la siguiente sintaxis:

Sintaxis

<?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>

Ejemplo

En el siguiente ejemplo, si un desarrollador no compró una suscripción al producto de API asociado, se bloquea el acceso a la API monetizada y se muestra un estado 403 con un mensaje personalizado.

<?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>

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

Atributo	Predeterminada	(obligatorio)	Descripción
name	N/A	Obligatorio	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
continueOnError	falso	Opcional	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
enabled	true	Opcional	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async	falso	Obsoleta	Este atributo dejó de estar disponible.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <MonetizationLimitsCheck>.

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omites <DisplayName>, se usa el valor del atributo name de la política.
Tipo	String
Elemento principal	<PolicyElement>
Elementos secundarios	Ninguno

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

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

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<FaultResponse>

Define el mensaje de respuesta que se muestra al cliente solicitante. FaultResponse usa la misma configuración que el elemento <FaultResponse> en la política RaiseFault.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<MonetizationLimitsCheck>
Elementos secundarios	<AssignVariable> <Add> <Copy> <Remove> <Set>

<AssignVariable>

Asigna un valor a una variable de flujo de destino. Si la variable de flujo no existe, AssignVariable la crea.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<FaultResponse>
Elementos secundarios	<Name> <Value>

Por ejemplo, usa el siguiente código para establecer la variable llamada myFaultVar en la política MonetizationLimitsCheck:

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

De este modo, una política en una regla de falla puede acceder a la variable. Por ejemplo, la siguiente política AssignMessage usa la variable para configurar un encabezado en la respuesta de falla:

<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>

<AssignVariable> en la política MonetizationLimitsCheck usa la misma sintaxis que el elemento <AssignVariable> en la política AssignMessage.

<Name>

Nombre de la variable Para obtener más información, consulta el elemento Nombre en la política AssignMessage.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<AssignVariable>
Elementos secundarios	Ninguno

<Value>

Valor de la variable. Para obtener más información, consulta el elemento Valor en la política AssignMessage.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<AssignVariable>
Elementos secundarios	Ninguno

<Add>

Agrega encabezados HTTP al mensaje de error.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<FaultResponse>
Elementos secundarios	<Headers>

<Headers>

Especifica el encabezado HTTP que se agrega, configura, copia o quita.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<Add> <Copy> <Remove> <Set>
Elementos secundarios	Ninguno

• Un encabezado vacío (<Add><Headers/></Add>) no agrega ningún encabezado.
• <Header>El elemento admite la función de sustitución dinámica de string llamada plantillas de mensajes.

Ejemplos:

Agregar encabezado

En el siguiente ejemplo, se copia el valor de la variable de flujo request.user.agent en el encabezado:

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

Establecer encabezado

En el siguiente ejemplo, se establece el encabezado user-agent en la variable de mensaje especificada con el elemento <AssignTo>.

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

Copiar encabezado - 1

En el siguiente ejemplo, se copia el headerA de la solicitud:

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

Copiar encabezado - 2

En el siguiente ejemplo, se copian varios encabezados:

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

En este ejemplo, se copia “h1”, “h2” y el segundo valor de “h3”. Si “h3” tiene un solo valor, no se copia “h3”.

Quitar encabezado - 1

En el siguiente ejemplo, se quita un encabezado:

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

Quitar encabezado - 2

En el siguiente ejemplo, se quitan varios encabezados:

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

En este ejemplo, se quita “h1”, “h2” y el segundo valor de “h3”. Si “h3” tiene solo un valor, no se quita “h3”.

<Copy>

Copia de la información desde el mensaje especificado por el atributo source en el mensaje de error.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<FaultResponse>
Elementos secundarios	<Headers> <StatusCode>

En la siguiente tabla, se describen los atributos de <Copy>:

Atributo	¿Es obligatorio?	Tipo	Descripción
fuente	Opcional	String	Especifica el objeto de origen de la copia. Si source no se especifica, se lo trata como un mensaje simple. Por ejemplo, si la política está en el flujo de solicitud, la fuente predeterminada tiene como configuración el objeto request. Si la política está en el flujo de respuesta, su valor predeterminado es el objeto response. Si omites source, puedes usar una referencia absoluta a una variable de flujo como la fuente de la copia. Por ejemplo, especifica el valor como {request.header.user-agent}. Si la variable de origen no se puede resolver o se resuelve en un tipo que no es de mensaje, <Copy> no responde.

<StatusCode>

Especifica el código de estado HTTP en el mensaje de error. Puedes copiar o configurar el valor del objeto especificado por el atributo source.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<Copy> <Set>
Elementos secundarios	Ninguno

Ejemplo:

Copiar código de estado

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

Establecer código de estado

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

<Remove>

Quita los encabezados HTTP especificados del mensaje de error. Para quitar todos los encabezados, especifica <Remove><Headers/></Remove>.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<FaultResponse>
Elementos secundarios	<Headers>

<Set>

Establece la información en el mensaje de error.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	Tipo complejo
Elemento principal	<FaultResponse>
Elementos secundarios	<Headers> <Payload> <StatusCode>

<Payload>

Configura la carga útil del mensaje de error.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	<Set>
Elementos secundarios	Ninguno

Ejemplos:

Establecer carga útil de texto

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

Establecer carga útil de JSON - 1

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

Establecer la carga útil de JSON - 2

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

En este ejemplo, se insertan variables mediante los atributos variablePrefix y variableSuffix con caracteres delimitadores.

Establecer carga útil de JSON - 3

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

En este ejemplo, se insertan variables mediante llaves. Puedes usar llaves a partir de la versión 16.08.17.

Establece la carga útil XML

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

En este ejemplo, se insertan variables mediante llaves. Puedes usar llaves a partir de la versión 16.08.17.

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando se encuentra una variable sin resolver.

Configúralo como true para ignorar las variables sin resolver y continuar con el procesamiento, de lo contrario, false. El valor predeterminado es true.

Configurar <IgnoreUnresolvedVariables> como true es diferente a configurar continueOnError como <MonetizationLimitsCheck> en true. Si configuras continueOnError como true, Apigee ignora todos los errores, no solo los errores de las variables.

El elemento <IgnoreUnresolvedVariables> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el siguiente ejemplo, se configura <IgnoreUnresolvedVariables> como false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Códigos de error

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla	Estado de HTTP	Causa
mint.service.subscription_not_found_for_developer	500	Este error ocurre cuando un desarrollador no tiene una suscripción al producto de API.
mint.service.wallet_not_found_for_developer	500	Este error ocurre cuando un desarrollador prepago intenta consumir una API monetizada sin mantener una cartera para la moneda especificada en el plan de tarifas.
mint.service.developer_usage_exceeds_balance	500	Este error ocurre cuando el uso de un desarrollador prepago supera el saldo de cartera.
mint.service.wallet_blocked_due_to_inactivity	500	Este error ocurre cuando la cartera de un desarrollador prepago no agrega dinero durante más de 1.5 años y el desarrollador intenta consumir una API.

Variables con fallas

Cuando hay errores de ejecución en una política, Apigee genera mensajes de error. Puedes ver estos mensajes de error en la respuesta de error. Es posible que muchos mensajes de error generados por el sistema no sean relevantes en el contexto de tu producto. Te recomendamos personalizar los mensajes de error según el tipo de error para que los mensajes sean más significativos.

Para personalizar los mensajes de error, puedes usar reglas de falla o la política RaiseFault. Para obtener información sobre las diferencias entre las reglas de fallas y la política RaiseFault, consulta Política FaultRules en comparación con la política RaiseFault. Debes verificar las condiciones mediante el elemento Condition en las reglas de fallas y la política RaiseFault. Apigee proporciona variables de fallas únicas para cada política, y los valores de las variables de fallas se establecen cuando una política activa errores de entorno de ejecución. Si usas estas variables, puedes verificar las condiciones de error específicas y tomar las medidas adecuadas. Si deseas obtener más información para verificar las condiciones de error, consulta Condiciones de compilación.

Variables	Donde	Ejemplo
fault.name	El fault.name puede coincidir con cualquiera de las fallas enumeradas en la tabla Errores del entorno de ejecución. El nombre de la falla es la última parte del código de la falla.	fault.name Matches "UnresolvedVariable"
MonetizationLimitsCheck.POLICY_NAME.failed	POLICY_NAME es el nombre especificado por el usuario de la política que generó la falla.	MonetizationLimitsCheck.monetization-limits-check-1.failed = true

Para obtener más información sobre los errores de políticas, consulta Qué debes saber sobre los errores de políticas.

Variables de flujo

Las siguientes variables de flujo predefinidas se propagan automáticamente cuando se ejecuta la política MonetizationLimitsCheck. Para obtener más información, consulta las variables de flujo mint.

Variable de flujo	Descripción
mint.limitscheck.is_request_blocked	true para las solicitudes bloqueadas.
mint.limitscheck.is_subscription_found	true si se encuentra una suscripción a la API
mint.limitscheck.purchased_product_name	Nombre del producto de la API comprado. Por ejemplo: MyProduct.
mint.limitscheck.status_message	Mensaje de estado. Por ejemplo: limits_check_success.
mint.subscription_end_time_ms	Hora de finalización de la suscripción al producto de API.
mint.subscription_start_time_ms	Hora de inicio de la suscripción al producto de API. Por ejemplo: 1618433956209.