Política MonetizationLimitsCheck

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

Consulta la documentación de Apigee Edge.

Nota: La política MonetizationLimitsCheck solo es válida si has habilitado la monetización de Apigee en tu organización.

Información general

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

En concreto, la política se activa si el desarrollador de la aplicación que accede a la API monetizada no ha comprado una suscripción al producto de API asociado o si no tiene saldo suficiente. En este caso, la política MonetizationLimitsCheck generará un error y bloqueará una llamada a la API. Para obtener más información, consulta el artículo sobre cómo obligar a los desarrolladores a suscribirse a productos de API.

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

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Nota: A pesar de usar la política MonetizationLimitsCheck, es posible que se permita a un desarrollador prepago hacer llamadas a la API en exceso y que el desarrollador acabe con un saldo negativo en la cartera. Para saber en qué condiciones el saldo de un desarrollador se vuelve negativo, consulta Saldo negativo del 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 ofrece una descripción general 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 devuelve al cliente que ha enviado la solicitud.
<IgnoreUnresolvedVariables>	Opcional	Ignora cualquier error de variable sin resolver en el flujo.

El elemento <MonetizationLimitsCheck> utiliza 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 ha comprado una suscripción al producto de API asociado, se bloqueará el acceso a la API monetizada y se devolverá el 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	Predeterminado	¿Es 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. Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
continueOnError	falso	Opcional	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual
enabled	true	Opcional	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
async	falso	Obsoleto	Este atributo está obsoleto.

Referencia de elemento secundario

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

<DisplayName>

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

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

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

El elemento <DisplayName> utiliza 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 devuelve al cliente que ha enviado la solicitud. FaultResponse usa los mismos ajustes que el elemento <FaultResponse> de 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 definir la variable llamada myFaultVar en la política MonetizationLimitsCheck:

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

Una política de una regla de error puede acceder a la variable. Por ejemplo, la siguiente política AssignMessage usa la variable para definir un encabezado en la respuesta de error:

<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 Name de la política AssignMessage.

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

<Value>

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

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

<Add>

Añade 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 va a añadir, definir, copiar o quitar.

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 añade ningún encabezado.
• El elemento <Header> admite la función de sustitución de cadenas dinámicas llamada plantillas de mensajes.

Ejemplos:

Añadir 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>

Definir encabezado

En el siguiente ejemplo se asigna la cabecera user-agent a 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 copian "h1", "h2" y el segundo valor de "h3". Si "h3" solo tiene un valor, no se copia.

Quitar encabezado - 1

En el siguiente ejemplo se elimina un encabezado:

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

Quitar encabezado - 2

En el siguiente ejemplo se eliminan varios encabezados:

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

En este ejemplo, se eliminan "h1", "h2" y el segundo valor de "h3". Si "h3" solo tiene un valor, no se elimina.

<Copy>

Copia la información de 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	Cadena	Especifica el objeto de origen de la copia. Si no se especifica source, se trata como un mensaje simple. Por ejemplo, si la política está en el flujo de solicitud, la fuente se asigna de forma predeterminada al objeto request. Si la política se encuentra en el flujo de respuesta, se asigna de forma predeterminada al objeto response. Si omite source, puede usar una referencia absoluta a una variable de flujo como origen de la copia. Por ejemplo, especifique el valor {request.header.user-agent}. Si no se puede resolver la variable de origen o se resuelve en un tipo que no es de mensaje, se produce un error en <Copy>.

<StatusCode>

Especifica el código de estado HTTP en el mensaje de error. Puede copiar o definir el valor de para el 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>

Definir código de estado

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

<Remove>

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

Define la información del mensaje de error.

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

<Payload>

Define la carga útil del mensaje de error.

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

Ejemplos:

Definir carga útil de texto

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

Definir carga útil de JSON (1)

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

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

Definir 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 del 17/08/2016.

Definir 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 del 17/08/2016.

<IgnoreUnresolvedVariables>

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

Asigna el valor true para ignorar las variables sin resolver y continuar con el procesamiento. De lo contrario, asigna el valor false. El valor predeterminado es true.

Asignar el valor true a <IgnoreUnresolvedVariables> no es lo mismo que asignar el valor true a continueOnError de <MonetizationLimitsCheck>. Si asigna el valor true a continueOnError, Apigee ignora todos los errores, no solo los de las variables.

El elemento <IgnoreUnresolvedVariables> utiliza la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el siguiente ejemplo se asigna false a <IgnoreUnresolvedVariables>:

<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 rellenan 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 API comprado. Por ejemplo: MyProduct.
mint.limitscheck.status_message	Mensaje de estado. Se pueden devolver los siguientes valores: limits_check_success: comprobación de límites correcta. apiproduct_name_and_developer_email_not_available - No se puede determinar el desarrollador de la API ni el nombre del producto de la API para comprobar los límites. apiproduct_name_not_available - No se ha podido determinar el nombre del producto de la API para comprobar los límites. developer_email_not_available - No se ha podido determinar el correo del desarrollador de la API para comprobar los límites. developer_usage_exceeds_balance - El saldo de prepago del desarrollador es demasiado bajo. rateplan_not_available - Producto de API sin plan de tarifas, sin errores. subscription_not_available - El desarrollador de la API que es propietario de la aplicación no tiene una suscripción. wallet_disabled_due_to_inactivity: el desarrollador no ha usado su cartera en más de un año. Para reactivarla, debes añadir al menos una unidad (en dólares, sería 0,01 USD). wallet_not_found: el desarrollador no tiene una cartera. Esto puede ocurrir cuando no se ha realizado ninguna recarga para ese desarrollador.
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.