Política MonetizationLimitsCheck

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Informações gerais

A política MonetizationLimitsCheck permite que você aplique limites de monetização.

Especificamente, a política será acionada se o desenvolvedor de apps que acessa a API monetizada não tiver comprado uma assinatura do produto de API associado ou se o desenvolvedor não tiver saldo suficiente. Neste caso, a política MonetizationLimitsCheck gera uma falha e bloqueia uma chamada de API. Para mais informações, consulte Como aplicar assinaturas de desenvolvedor a produtos de API.

Ao anexar a política MonetizationLimitsCheck em um proxy de API, as variáveis de fluxo mint.limitscheck.* e mint.subscription_* são preenchidas, conforme descrito na referência da variável de fluxo mint.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

`<MonetizationLimitsCheck>`

Define a política MonetizationLimitsCheck.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	Tipo complexo
Elemento pai	N/A
Elemento filho	`<DisplayName>` `<FaultResponse>` `<IgnoreUnresolvedVariables>`

A tabela a seguir fornece uma descrição de alto nível dos elementos-filhos de <MonetizationLimitsCheck>:

Elemento filho	Obrigatório?	Descrição
`<DisplayName>`	Opcional	Um nome personalizado para a política.
`<FaultResponse>`	Opcional	Define a mensagem de resposta retornada ao cliente solicitante.
`<IgnoreUnresolvedVariables>`	Opcional	Ignora qualquer erro de variável não resolvido no fluxo.

O elemento <MonetizationLimitsCheck> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

No exemplo a seguir, se um desenvolvedor não tiver comprado assinatura do produto de API associado, o acesso à API monetizada será bloqueado e um status 403 será retornado com uma mensagem personalizada.

<?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 tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
`name`	N/A	Valor	O nome interno da política. O valor do atributo `name` pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento `<DisplayName>` para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
`continueOnError`	falso	Opcional	Defina como `false` para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como `true` para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
`enabled`	true	Opcional	Defina como `true` para aplicar a política. Defina como `false` para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
`async`	falso	Obsoleto	Esse atributo está obsoleto.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <MonetizationLimitsCheck>.

`<DisplayName>`

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir `<DisplayName>`, o valor do atributo `name` da política será usado
Tipo	String
Elemento pai	<`PolicyElement`>
Elemento filho	Nenhuma

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

O elemento <DisplayName> não tem atributos ou elementos filhos.

`<FaultResponse>`

Define a mensagem de resposta retornada ao cliente solicitante. O FaultResponse usa as mesmas configurações do elemento <FaultResponse> na política RaiseFault.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<MonetizationLimitsCheck>`
Elemento filho	`<AssignVariable>` `<Add>` `<Copy>` `<Remove>` `<Set>`

`<AssignVariable>`

Atribui um valor a uma variável de fluxo de destino. Se a variável de fluxo não existir, a AssignVariable a criará.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<FaultResponse>`
Elemento filho	`<Name>` `<Value>`

Por exemplo, use o código a seguir para definir a variável chamada myFaultVar na política MonetizationLimitsCheck:

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

Uma política em uma regra de falha pode acessar a variável. Por exemplo, a seguinte política de atribuição de mensagens usa a variável para definir um cabeçalho na resposta da falha:

<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> na política MonetizationLimitsCheck usa a mesma sintaxe do elemento <AssignVariable> na política AssignMessage.

`<Name>`

Nome da variável. Para mais informações, consulte o elemento Nome na política AttributionMessage.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	`<AssignVariable>`
Elemento filho	Nenhum

`<Value>`

Valor da variável. Para mais informações, consulte o elemento Value na política AttributionMessage.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	`<AssignVariable>`
Elemento filho	Nenhum

`<Add>`

Adiciona cabeçalhos HTTP à mensagem de erro.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<FaultResponse>`
Elemento filho	`<Headers>`

`<Headers>`

Especifica o cabeçalho HTTP que será adicionado, definido, copiado ou removido.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<Add>` `<Copy>` `<Remove>` `<Set>`
Elemento filho	Nenhum

Exemplos:

Adicionar cabeçalho

O exemplo a seguir copia o valor da variável de fluxo request.user.agent para o cabeçalho:

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

Definir cabeçalho

O exemplo a seguir define o cabeçalho user-agent como a variável de mensagem especificada com o elemento <AssignTo>.

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

Copiar cabeçalho - 1

O exemplo a seguir copia o headerA da solicitação:

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

Copiar cabeçalho - 2

O exemplo a seguir copia vários cabeçalhos:

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

Este exemplo copia "h1", "h2" e o segundo valor de "h3". Se "h3" tiver apenas um valor, "h3" não será copiado.

Remover cabeçalho - 1

O exemplo a seguir remove um cabeçalho:

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

Remover cabeçalho - 2

O exemplo a seguir remove vários cabeçalhos:

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

Este exemplo remove "h1", "h2" e o segundo valor de "h3". Se "h3" tiver apenas um valor, "h3" não será removido.

`<Copy>`

Copia informações da mensagem especificada pelo atributo source para a mensagem de erro.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<FaultResponse>`
Elemento filho	`<Headers>` `<StatusCode>`

A tabela a seguir descreve os atributos de <Copy>:

Atributo	Obrigatório?	Tipo	Descrição
source	Opcional	String	Especifica o objeto de origem da cópia. Se não for especificado, source será tratada como uma mensagem simples. Por exemplo, se a política estiver no fluxo de solicitações, a origem será padrão para o objeto request. Se a política estiver no fluxo de resposta, o padrão será o objeto response. Se você omitir a source, poderá usar uma referência absoluta a uma variável de fluxo como a origem da cópia. Por exemplo, especifique o valor como {request.header.user-agent}. Se a variável de origem não puder ser resolvida ou resolvida para um tipo não mensagem, <Copy> não responderá.

Atributo

Obrigatório?

Tipo

Descrição

source

Opcional

String

Especifica o objeto de origem da cópia.

Se não for especificado, source será tratada como uma mensagem simples. Por exemplo, se a política estiver no fluxo de solicitações, a origem será padrão para o objeto request. Se a política estiver no fluxo de resposta, o padrão será o objeto response. Se você omitir a source, poderá usar uma referência absoluta a uma variável de fluxo como a origem da cópia. Por exemplo, especifique o valor como {request.header.user-agent}.
Se a variável de origem não puder ser resolvida ou resolvida para um tipo não mensagem, <Copy> não responderá.

`<StatusCode>`

Especifica o código de status HTTP na mensagem de erro. É possível copiar ou definir o valor do objeto especificado pelo atributo source.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<Copy>` `<Set>`
Elemento filho	Nenhum

Exemplo:

Copiar código de status

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

Definir código de status

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

`<Remove>`

Remove os cabeçalhos HTTP especificados da mensagem de erro. Para remover todos os cabeçalhos, especifique <Remove><Headers/></Remove>.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<FaultResponse>`
Elemento filho	`<Headers>`

`<Set>`

Define as informações na mensagem de erro.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<FaultResponse>`
Elemento filho	`<Headers>` `<Payload>` `<StatusCode>`

`<Payload>`

Define o payload da mensagem de erro.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	`<Set>`
Elemento filho	Nenhum

Exemplos:

Definir payload do texto

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

Definir payload JSON: 1

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

Definir payload JSON: 2

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

Este exemplo insere variáveis usando os atributos variablePrefix e variableSuffix com caracteres delimitadores.

Definir payload JSON: 3

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

Este exemplo insere variáveis usando chaves. Você pode usar chaves a partir da versão 16.08.17.

Definir payload XML

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

Este exemplo insere variáveis usando chaves. Você pode usar chaves a partir da versão 16.08.17.

`<IgnoreUnresolvedVariables>`

Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.

Defina como true para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, false. O valor padrão é true.

Definir <IgnoreUnresolvedVariables> como true é diferente de definir o continueOnError do <MonetizationLimitsCheck> como true. Se você definir continueOnError como true, a Apigee vai ignorar todos os erros, e não apenas os erros nas variáveis.

O elemento <IgnoreUnresolvedVariables> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo a seguir define <IgnoreUnresolvedVariables> como false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Códigos de erro

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha	Status HTTP	Causa
`mint.service.subscription_not_found_for_developer`	`500`	Esse erro ocorre quando um desenvolvedor não tem uma assinatura do produto de API.
`mint.service.wallet_not_found_for_developer`	`500`	Esse erro ocorre quando um desenvolvedor pré-pago tenta consumir uma API que gera receita sem manter uma carteira com a moeda especificada no plano de tarifas.
`mint.service.developer_usage_exceeds_balance`	`500`	Esse erro ocorre quando o uso de um desenvolvedor pré-pago excede o saldo da carteira.
`mint.service.wallet_blocked_due_to_inactivity`	`500`	Esse erro ocorre quando a carteira de um desenvolvedor pré-pago não termina com mais de 1,5 ano e o desenvolvedor tenta consumir uma API.

Variáveis de falha

Sempre que houver erros de execução em uma política, a Apigee gerará mensagens de erro. Essas mensagens de erro podem ser visualizadas na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do produto. Personalize as mensagens de erro com base no tipo específico para torná-las mais úteis.

Para personalizar as mensagens de erro, use regras de falha ou a política RaiseFault. Para informações sobre as diferenças entre as regras de falha e a política RaiseFault, consulte FaultRules vs. a política RaiseFault. Verifique as condições usando o elemento Condition nas regras de falha e na política RaiseFault. A Apigee fornece variáveis de falha exclusivas para cada política, e os valores das variáveis de falha são definidos quando uma política aciona erros de ambiente de execução. Ao usar essas variáveis, é possível verificar se há condições de erro específicas e agir conforme adequado. Para mais informações sobre como verificar condições de erro, consulte Como criar condições.

Variáveis	Onde	Exemplo
`fault.name`	O `fault.name` pode corresponder a qualquer uma das falhas listadas na tabela Erros de ambiente de execução. O nome da falha é a última parte do código de falha.	`fault.name Matches "UnresolvedVariable"`
`MonetizationLimitsCheck.POLICY_NAME.failed`	`POLICY_NAME` é o nome da política especificada pelo usuário que gerou a falha.	`MonetizationLimitsCheck.monetization-limits-check-1.failed = true`

Para mais informações sobre erros de política, consulte O que você precisa saber sobre erros de política

Variáveis de fluxo

As variáveis de fluxo predefinidas a seguir são preenchidas automaticamente quando a política MonetizationLimitsCheck é executada. Para mais informações, consulte as variáveis de fluxo mint.

Variável de fluxo	Descrição
`mint.limitscheck.is_request_blocked`	`true` para solicitações bloqueadas.
`mint.limitscheck.is_subscription_found`	`true`, se uma assinatura de API for encontrada
`mint.limitscheck.purchased_product_name`	Nome do produto de API comprado. Por exemplo, `MyProduct`.
`mint.limitscheck.status_message`	Mensagem de status. Por exemplo, `limits_check_success`.
`mint.subscription_end_time_ms`	Horário de término da assinatura do produto de API.
`mint.subscription_start_time_ms`	Horário de início da assinatura do produto de API. Por exemplo, `1618433956209`.