Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
Vista geral
A política MonetizationLimitsCheck permite-lhe aplicar limites de rentabilização.
Especificamente, a política é acionada se o programador da app que acede à API rentabilizada não tiver comprado uma subscrição do produto API associado ou se o programador tiver um saldo insuficiente. Neste caso, a política MonetizationLimitsCheck gera uma falha e bloqueia uma chamada API. Para mais informações, consulte o artigo Aplicação de subscrições de programadores a produtos de API.
Quando anexa a política MonetizationLimitsCheck a 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 política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.
<MonetizationLimitsCheck>
Define a política MonetizationLimitsCheck.
Valor predefinido | N/A |
Obrigatório? | Obrigatória |
Tipo | Tipo complexo |
Elemento principal | N/A |
Elementos subordinados |
<DisplayName> <FaultResponse> <IgnoreUnresolvedVariables> |
A tabela seguinte fornece uma descrição geral dos elementos subordinados de <MonetizationLimitsCheck>
:
Elemento secundário | Obrigatório? | Descrição |
---|---|---|
<DisplayName> |
Opcional | Um nome personalizado para a política. |
<FaultResponse> |
Opcional | Define a mensagem de resposta devolvida ao cliente que está a fazer o pedido. |
<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 seguinte, se um programador não tiver comprado uma subscrição do produto API associado, o acesso à API rentabilizada é bloqueado e é devolvido um estado 403
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 | Predefinição | Obrigatório? | Descrição |
---|---|---|---|
name |
N/A | Obrigatório |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
continueOnError |
falso | Opcional | Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:
|
enabled |
verdadeiro | Opcional | Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo. |
async |
falso | Descontinuado | Este atributo foi descontinuado. |
Referência de elemento secundário
Esta secção descreve os elementos subordinados de<MonetizationLimitsCheck>
.
<DisplayName>
Use em conjunto com o atributo name
para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.
O elemento <DisplayName>
é comum a todas as políticas.
Valor predefinido | N/A |
Obrigatório? | Opcional. Se omitir <DisplayName> , é usado o valor do atributo name da política. |
Tipo | String |
Elemento principal | <PolicyElement> |
Elementos subordinados | 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 nem elementos subordinados.
<FaultResponse>
Define a mensagem de resposta devolvida ao cliente que está a fazer o pedido. FaultResponse usa as mesmas definições que o elemento <FaultResponse
> no elemento RaiseFault.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<MonetizationLimitsCheck> |
Elementos subordinados |
<AssignVariable> <Add> <Copy> <Remove> <Set> |
<AssignVariable>
Atribui um valor a uma variável do fluxo de destino.
Se a variável de fluxo não existir, o elemento AssignVariable
cria-a.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<FaultResponse> |
Elementos subordinados |
<Name> <Value> |
Por exemplo, use o código seguinte para definir a variável denominada myFaultVar
na política MonetizationLimitsCheck:
<FaultResponse> <AssignVariable> <Name>myFaultVar</Name> <Value>42</Value> </AssignVariable> </FaultResponse>
Uma política numa regra de falha pode, então, aceder à variável. Por exemplo, a seguinte política AssignMessage usa a variável para definir um cabeçalho na resposta de 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 que o elemento <AssignVariable>
na política AssignMessage.
<Name>
Nome da variável. Para mais informações, consulte o elemento Name no elemento AssignMessage.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | String |
Elemento principal |
<AssignVariable> |
Elementos subordinados | Nenhum |
<Value>
Valor da variável. Para mais informações, consulte o elemento Value na política AssignMessage.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | String |
Elemento principal |
<AssignVariable> |
Elementos subordinados | Nenhum |
<Add>
Adiciona cabeçalhos HTTP à mensagem de erro.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<FaultResponse> |
Elementos subordinados |
<Headers> |
<Headers>
Especifica o cabeçalho HTTP a adicionar, definir, copiar ou remover.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<Add> <Copy> <Remove> <Set> |
Elementos subordinados | Nenhum |
Exemplos:
Adicionar cabeçalho
O exemplo seguinte 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 seguinte define o cabeçalho user-agent
para 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 seguinte copia o headerA
do pedido:
<Copy source='request'> <Headers> <Header name="headerA"/> </Headers> </Copy>
Copiar cabeçalho – 2
O exemplo seguinte 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 é copiado.
Remover cabeçalho - 1
O exemplo seguinte remove um cabeçalho:
<Remove> <Headers> <Header name="user-agent"/> </Headers> </Remove>
Remover cabeçalho – 2
O exemplo seguinte 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 é removido.
<Copy>
Copia informações de da mensagem especificada pelo atributo source
para a mensagem de erro.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<FaultResponse> |
Elementos subordinados |
<Headers> <StatusCode> |
A tabela seguinte descreve os atributos de <Copy>
:
Atributo | Obrigatório? | Tipo | Descrição |
---|---|---|---|
fonte | Opcional | String |
Especifica o objeto de origem da cópia.
|
<StatusCode>
Especifica o código de estado HTTP na mensagem de erro. Pode copiar ou definir o valor de
para o objeto especificado pelo atributo source
.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<Copy> <Set> |
Elementos subordinados | Nenhum |
Exemplo:
Copie o código de estado
<Copy source='response'> <StatusCode>404</StatusCode> </Copy>
Defina o código de estado
<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 predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<FaultResponse> |
Elementos subordinados |
<Headers> |
<Set>
Define informações na mensagem de erro.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | Tipo complexo |
Elemento principal |
<FaultResponse> |
Elementos subordinados |
<Headers> <Payload> <StatusCode> |
<Payload>
Define o payload da mensagem de erro.
Valor predefinido | N/A |
Obrigatório? | Opcional |
Tipo | String |
Elemento principal |
<Set> |
Elementos subordinados | Nenhum |
Exemplos:
Defina o payload de 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 carateres delimitadores.
Defina o payload de JSON – 3
<Set> <Payload contentType="application/json"> {"name":"foo", "type":"{variable_name}"} </Payload> </Set>
Este exemplo insere variáveis com chavetas. Pode usar chavetas a partir da versão de 16/08/17.
Defina o payload XML
<Set> <Payload contentType="text/xml"> <root> <e1>sunday</e1> <e2>funday</e2> <e3>{var1}</e3> </Payload> </Set>
Este exemplo insere variáveis com chavetas. Pode usar chavetas a partir da versão de 16/08/17.
<IgnoreUnresolvedVariables>
Determina se o processamento é interrompido quando é encontrada uma variável não resolvida.
Definido como true
para ignorar as variáveis não resolvidas e continuar o processamento; caso contrário, false
. O valor predefinido é true
.
Definir <IgnoreUnresolvedVariables>
como true
é diferente de definir o <MonetizationLimitsCheck>
de
continueOnError
como true
. Se definir continueOnError
como true
, o Apigee ignora todos os erros, não apenas os erros nas variáveis.
O elemento <IgnoreUnresolvedVariables>
usa a seguinte sintaxe:
Sintaxe
<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
Exemplo
O exemplo seguinte 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 |
Variáveis de fluxo
As seguintes variáveis de fluxo predefinidas 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 pedidos bloqueados. |
mint.limitscheck.is_subscription_found |
true se for encontrada uma subscrição da API. |
mint.limitscheck.purchased_product_name |
Nome do produto API comprado. Por exemplo: MyProduct . |
mint.limitscheck.status_message |
Mensagem de estado. Estes são os valores que podem ser devolvidos:
|
mint.subscription_end_time_ms |
Hora de conclusão da subscrição do produto API. |
mint.subscription_start_time_ms |
Hora de início da subscrição do produto API. Por exemplo: 1618433956209 . |