Configurar plano de tarifa com atributos personalizados

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Introdução

Em alguns casos, pode ser necessário que os contadores de transação se baseiem em uma variável ou valor personalizado. Por exemplo, talvez seja necessário:

• Cobrar dos desenvolvedores um valor variável com base em um valor fornecido na mensagem de uma chamada de API. Por exemplo, você pode cobrar dos desenvolvedores de apps com base no número de bytes transmitidos na solicitação de API.
• Agrupar várias chamadas de API em uma única transação.

Ao usar planos de preços com atributos personalizados, é possível identificar um valor na mensagem de uma chamada de API que funciona como contador e é usado para calcular a contagem de transações e cobranças.

Os seguintes planos de preços com atributos personalizados são aceitos:

• Tabela de preços com atributo personalizado
• Notificação ajustável com atributo personalizado

É possível definir até 10 atributos personalizados por plano de preços.

Como entender os cálculos de atributos personalizados

A forma como o valor do atributo personalizado é considerado nas contagens e cobranças de transações do plano de tarifas depende do modelo de cobrança, conforme resumido na tabela a seguir.

Modelo de carregamento	Cálculo de atributos personalizados
Taxa fixa e volume com faixas	custom attribute number * rate = charge to developer Para uma taxa fixa, o número do atributo personalizado se torna o número de transações multiplicados pela taxa. No caso de Volume Banded, o número de transações em uma faixa é incrementado pelo número de atributos personalizados, e o desenvolvedor é cobrado por esse número de transações. Por exemplo, se o valor de um atributo personalizado na mensagem for 10, o desenvolvedor vai receber cobrança por 10 transações, e 10 transações serão adicionadas à contagem de faixas atual. Se o desenvolvedor tiver apenas seis transações restantes na faixa atual, o número 6 será multiplicado pela taxa dessa faixa. Os quatro restantes vão para a próxima faixa e são multiplicados pela taxa dessa faixa. Em um plano com faixa de volume, se a última faixa tiver um limite (não for "ilimitado") e uma transação exceder esse limite, duas coisas vão acontecer: O desenvolvedor recebe o valor "acima" sem custo financeiro. O app do desenvolvedor é impedido de fazer outras chamadas à API até o período do plano ser redefinido. Consulte Quando as taxas recorrentes são cobradas e os planos de pacote são redefinidos? para mais detalhes.
Pacotes	Como os pacotes são cobrados pelo grupo, não pela transação, ocorre o seguinte cálculo: custom attribute number = amount added to bundle count Por exemplo, se o número do atributo personalizado na mensagem for 10, 10 será adicionado ao número de transações usadas no pacote. Se o desenvolvedor tiver apenas seis transações restantes no pacote atual, esse pacote será preenchido e a próxima contagem de pacotes será incrementada em quatro. A taxa para o próximo pacote, se houver, será cobrada. Se o último pacote tiver um limite (não for "ilimitado") e uma transação exceder esse limite, duas coisas vão acontecer: O desenvolvedor recebe o valor excedente sem custo financeiro. O app do desenvolvedor é bloqueado para fazer outras chamadas para a API até que o período do plano seja redefinido. Consulte Quando as taxas recorrentes são cobradas e os planos de pacote são redefinidos? para saber quando os planos são redefinidos.
Notificações ajustáveis	Para notificações ajustáveis, o seguinte cálculo ocorre: custom attribute number = amount added to transaction count Por exemplo, se o número do atributo personalizado na mensagem for 10, 10 será adicionado ao número total de transações.

Onde o plano de tarifas recebe o valor do atributo personalizado

A política de registro de transações (no pacote de produtos da API) informa à monetização onde procurar o valor do atributo personalizado na mensagem. Defina o atributo personalizado na seção "Atributos personalizados" da política de registro de transações do pacote de produtos da API.

Em seguida, selecione esse atributo personalizado no plano de tarifas depois de criar um pacote de produtos da API que contenha a política de registro de transações com o atributo personalizado definido.

Este é o fluxo geral:

1. Defina os atributos personalizados ao adicionar um produto de API.
2. Crie um pacote de produtos de API que contenha o produto.
   Na política de gravação de transações do pacote de produtos de API, adicione os atributos personalizados que serão usados para definir planos de tarifas.
3. Crie um plano de tarifas do tipo cartão de tarifas ou notificação ajustável para o pacote de produtos de API e especifique um parâmetro de classificação personalizado.

A figura a seguir mostra a relação entre o atributo personalizado definido na política de gravação de transações e a configuração do plano de tarifas. A notificação ajustável com a relação do plano de preço de atributo personalizado é semelhante, embora o valor da faixa de volume não seja aplicável.

Como gerar o valor do atributo personalizado na mensagem

A política de registro de transações pode procurar o valor do atributo personalizado em vários lugares, como o cabeçalho de resposta, o corpo da resposta ou as variáveis de fluxo predefinidas na resposta. A solicitação não está disponível porque uma transação não é oficial até que você receba uma resposta bem-sucedida. Veja a seguir exemplos de como adicionar um cabeçalho de resposta com o valor numérico dele à mensagem. Em ambos os casos, vamos usar a política Atribuir mensagem em conjunto com variáveis.

Adicionar tamanho de payload de solicitação ao cabeçalho de resposta

Em cada solicitação de mensagem, há uma variável client.received.content.length que contém o número de bytes no payload da solicitação. Ao anexar uma política de atribuição de mensagem à resposta do endpoint de proxy, podemos gerar um cabeçalho de resposta chamado messageSize que contém o valor de comprimento:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="messageSize">{client.received.content.length}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Como adicionar um valor de atributo personalizado do app ao cabeçalho

Da mesma forma, podemos gerar um cabeçalho com o valor de um atributo personalizado em um app. Por exemplo, se você incluir um atributo personalizado chamado apprating em cada app do desenvolvedor, conforme abaixo:

Ao usar a política Verificar chave de API (necessária para gerar receita), esse valor é armazenado em uma variável chamada verifyapikey.{policy_name}.apprating. Com a política "Atribuir mensagem" anexada à resposta do endpoint do proxy, é possível gerar um cabeçalho chamado apprating contendo o valor apprating do app:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="apprating">{verifyapikey.Verify-API-Key-1.apprating}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Configurar o plano de tarifas

Além da configuração de atributos personalizados descrita acima, o plano de preços é configurado da mesma forma que você normalmente faria (para planos de preços sem atributos personalizados), mas precisa obedecer aos requisitos a seguir.

Como configurar um plano de tabela de preços com atributo personalizado usando a interface

Configure planos de tarifas com atributos personalizados usando a interface do Edge ou a interface clássica do Edge, conforme descrito nas seções a seguir.

Como configurar um plano de notificação ajustável com atributos personalizados usando a interface

Configure planos de notificação ajustáveis com atributos personalizados, conforme descrito abaixo.

Como especificar detalhes de um plano de tarifas com atributos personalizados usando a API

Siga estas etapas de pré-requisito:

1. Na política de gravação de transações de um produto de API, adicione os atributos personalizados que serão usados para definir planos de tarifas. Para saber mais, consulte a introdução deste tópico e Criar uma política de gravação de transações. Faça isso para cada produto de API que você quer incluir no pacote.
2. Depois que as políticas de gravação de transações e de produtos de API estiverem configuradas da maneira que você quiser, crie um pacote de API que contenha o produto. Consulte Criar pacotes de API.

Em seguida, use a API para criar o plano de tarifas.

Você especifica detalhes para um plano de tarifas com atributos personalizados ao criar o plano. Você especifica os detalhes na propriedade ratePlanDetails no corpo da solicitação em uma chamada para /organizations/{org_name}/monetization-packages/{package_id}/rate-plans. Nos detalhes, você especifica um valor de parâmetro de classificação que identifica o nome do atributo personalizado. Também é possível especificar um valor de parâmetro de classificação que agregue o atributo personalizado em um intervalo de tempo especificado.

Consulte Configurações de detalhes de plano de preço para conferir uma lista completa de opções de detalhes de plano de preço.

Por exemplo, o código a seguir cria uma tabela de preços com um plano de atributo personalizado com base em um atributo personalizado chamado messageSize (confira os itens em negrito).

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "name": "Custom attribute-based rate card plan",
   "developer":null,
   "developerCategory":null,
   "currency": {
     "id" : "usd"
     },     
   "description": "Custom attribute-based rate card plan",
   "displayName" : "Custom attribute-based rate card plan",
   "frequencyDuration": "1",
   "frequencyDurationType": "MONTH",
   "earlyTerminationFee": "10",
   "monetizationPackage": {
      "id": "location"
        },
      "organization": {
       "id": "{org_name}"
      },    
   "paymentDueDays": "30",
   "prorate": "false",
   "published": "false",     
   "ratePlanDetails":[
      {
        "currency":{
           "id":"usd"
        },
      "duration":1,
      "durationType":"MONTH",
      "meteringType":"VOLUME",
      "paymentDueDays":"30",
      "ratingParameter":"messageSize",
      "ratingParameterUnit":"MB",
      "organization":{
         "id":"{org_name}"
      },
      "ratePlanRates":[
         {
           "rate":0.15,
           "startUnit":0,
           "type":"RATECARD",
           "endUnit":1000
         },
         {
           "rate":0.1,
           "startUnit":1000,
           "type":"RATECARD",
           "endUnit":null
         }
      ],
      "freemiumUnit":0,
      "freemiumDuration":0,
      "freemiumDurationType":"MONTH",
      "type":"RATECARD",
      "customPaymentTerm":false
      }
    ],
    "freemiumUnit":0,
    "freemiumDuration":0,
    "freemiumDurationType":"MONTH",
    "contractDuration":"1",
    "contractDurationType":"YEAR", 
    "recurringStartUnit": 1,
    "recurringType": "CALENDAR",
    "recurringFee": "10",
    "setUpFee": "10",
    "startDate": "2013-09-15 00:00:00",
    "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

O código a seguir cria uma notificação ajustável com um plano de tarifas de atributos personalizados com base em um atributo personalizado chamado messageSize (veja o item em negrito).

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "AdjustableNotification",
     "displayName": "Custom attribute-based adjustable notification plan",
     "description": "Custom attribute-based adjustable notification plan",
     "published": "true",  
     "organization": {
      "id": "myorg"
     },
     "startDate": "2016-04-15 00:00:00",
     "type": "STANDARD",
     "monetizationPackage": {
        "id": "p1",
        "name": "test"
     },
     "currency": {
        "id" : "usd",
        "name" : "USD"
     },
     "ratePlanDetails": [
        {
           "type": "USAGE_TARGET",
           "meteringType": "DEV_SPECIFIC",
           "duration": 1,
           "durationType": "MONTH",
           "ratingParameter": "messageSize",
           "ratingParameterUnit": "MB",
           "organization": {
             "id": "myorg"
           },
           "currency": {
             "id": "usd",
             "name": "USD"
           }
        }
     ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans"  \
-u email:password