Política MonetizationLimitsCheck

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

Confira a documentação da Apigee Edge.

Observação: a política MonetizationLimitsCheck é válida somente se você tiver ativado a monetização da Apigee na organização.

Visão geral

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.

Observação: em vez de usar a política MonetizeLimitsCheck, é possível que um desenvolvedor pré-pago tenha permissão para fazer chamadas de API em excesso, e o desenvolvedor pode acabar com um saldo negativo. Para entender as condições em que o saldo de um desenvolvedor se torna negativo, consulte Saldo negativo do desenvolvedor.

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

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

• Um cabeçalho vazio (<Add><Headers/></Add>) não adiciona nenhum cabeçalho.
• O elemento <Header> é compatível com o recurso de substituição de strings dinâmicas chamado modelo de mensagem.

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
fonte	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 de erro 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.