Configurar plano de tarifa com atributos personalizados

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Introdução

Em alguns casos, pode ser necessário que os contadores de transação sejam baseados em uma variável ou um 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, talvez você queira 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 tarifas com atributos personalizados, é possível identificar um valor na mensagem de uma chamada de API que funcione como contador. Esse valor será usado para calcular as contagens e as cobranças de transações.

Há suporte para os seguintes planos de tarifas com atributos personalizados:

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

É possível definir até dez atributos personalizados por plano de tarifa.

Noções básicas sobre os cálculos de atributos personalizados

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

Modelo de carregamento	Cálculo de atributo personalizado
Tarifa fixa e volume bandada	custom attribute number * rate = charge to developer No caso de uma taxa fixa, o número do atributo personalizado se torna o número de transações multiplicadas pela taxa. Para "Volume com banda", o número de transações em uma faixa é incrementado pelo número do atributo personalizado, 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 será cobrado por 10 transações, e 10 transações serão adicionadas à contagem de bandas atual. Se o desenvolvedor tiver apenas 6 transações restantes na banda atual, 6 será multiplicado pela taxa dessa banda. Os quatro restantes vão para a próxima faixa e são multiplicados pela taxa dessa faixa. Em um plano de volume com banda, se a última banda de volume tiver um limite (não "ilimitado") e uma transação exceder esse limite, duas coisas acontecerão: O desenvolvedor recebe sem custo financeiro o valor "acima". O app do desenvolvedor não pode fazer outras chamadas à 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 mais detalhes.
Bundles	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 6 transações restantes no pacote atual, ele será preenchido e a próxima contagem será incrementada em quatro. A tarifa do próximo pacote, se houver, será cobrada. Se o último pacote tiver um limite (não "ilimitado") e uma transação exceder esse limite, duas coisas acontecerão: O desenvolvedor recebe sem custo financeiro o valor "acima". O app do desenvolvedor não pode fazer outras chamadas à 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 mais detalhes.
Notificações ajustáveis	Para notificações ajustáveis, ocorre o seguinte cálculo: 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 tarifa 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. Você define o atributo personalizado na seção "Atributos personalizados" da política de registro de transações para o pacote de produtos da API.

Então, é possível selecionar 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 da API que contenha o produto.
   Na política de registro de transações do pacote de produtos da API, adicione os atributos personalizados que serão usados para definir planos de tarifas.
3. Crie um plano de preços do tipo tabela de preços ou notificação ajustável para o pacote de produtos da API e especifique um parâmetro de classificação personalizada.

A figura a seguir mostra a relação entre o atributo personalizado definido na política de registro de transações e a configuração do plano da tabela de preços. A notificação ajustável com a relação do plano de tarifa de atributos personalizados é semelhante, embora o valor de 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 no cabeçalho, no corpo ou nas 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 à mensagem. Em ambos os casos, usaremos a política Atribuir mensagem com as variáveis.

Como adicionar o tamanho do payload da 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 mensagens à 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>

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 de desenvolvedor, da seguinte maneira:

Ao usar a política "Verificar chave de API" (necessária para monetização), esse valor é armazenado em uma variável chamada verifyapikey.{policy_name}.apprating. Usando a política de atribuição de mensagem anexada à resposta do endpoint de proxy, é possível gerar um cabeçalho chamado apprating contendo o valor de 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>

Como configurar o plano de tarifas

Além da configuração de atributo personalizado descrita acima, o plano de tarifas é configurado da mesma maneira que você faria normalmente (para planos de tarifas sem atributos personalizados), mas precisa atender aos seguintes requisitos.

Configurar o plano de tabela de preços com atributo personalizado usando a interface

Configure planos de tabela de preços com atributos personalizados usando a interface do Edge ou a 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 tarifa com atributos personalizados usando a API

Siga estas etapas de pré-requisito:

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

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

Você especifica os detalhes de um plano de tarifas com atributos personalizados ao criá-lo. Especifique 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, especifique um valor de parâmetro de classificação que identifica o nome do atributo personalizado. Você também pode especificar um valor de parâmetro de classificação que agregue o atributo personalizado em um intervalo de tempo especificado.

Consulte as configurações de detalhes do plano de tarifa para conferir uma lista completa das opções de detalhes.

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 (veja 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 tarifa de atributo personalizado com base em um atributo personalizado chamado messageSize (consulte 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