Configura el plan de tarifas con atributos personalizados

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Introducción

En algunos casos, es posible que necesites que los contadores de transacciones se basen en una variable o un valor personalizado. Por ejemplo, es posible que debas hacer lo siguiente:

  • Cobra a los desarrolladores un importe variable según un valor proporcionado en el mensaje de una llamada a la API. Por ejemplo, es posible que quieras cobrar a los desarrolladores de apps según la cantidad de bytes que se transmiten en la solicitud a la API.
  • Agrupa varias llamadas a la API en una sola transacción.

Si usas los planes de tarifas con atributos personalizados, puedes identificar un valor en el mensaje de una llamada a la API que actúe como contador y que se use para calcular la cantidad y los cargos de transacciones.

Se admiten los siguientes planes de tarifas con atributos personalizados:

  • Hoja de tarifas con atributo personalizado
  • Notificación ajustable con atributo personalizado

Puedes establecer un máximo de diez atributos personalizados por plan de tarifas.

Información sobre los cálculos de atributos personalizados

La forma en que se tiene en cuenta el valor del atributo personalizado en los recuentos y cargos de las transacciones del plan de tarifas depende del modelo de cobro, como se resume en la siguiente tabla.

Modelo de carga Cálculo de atributos personalizados
Tarifa plana y por bandas de volumen

custom attribute number * rate = charge to developer

Para una tarifa plana, el número de atributo personalizado se convierte en la cantidad de transacciones que se multiplican por la tarifa. En el caso de las bandas por volumen, el número de transacciones en una banda aumenta según el número de atributo personalizado, y se le cobra al desarrollador por esa cantidad. Por ejemplo, si el valor de un atributo personalizado en el mensaje es 10, se le cobra al desarrollador por 10 transacciones, y se agregan 10 transacciones al recuento de banda actual. Si el desarrollador tenía solo 6 transacciones restantes en la banda actual, 6 se multiplica por la tasa de esa banda. Los 4 restantes pasan a la siguiente banda y se multiplican por la velocidad de esa banda.

En un plan por bandas por volumen, si la última banda de volumen tiene un límite (no es "ilimitado") y una transacción excede ese límite, suceden dos cosas:

Bundles

Dado que los paquetes se cobran por el grupo, no por la transacción, se realiza el siguiente cálculo:

custom attribute number = amount added to bundle count

Por ejemplo, si el número del atributo personalizado en el mensaje es 10, se suma 10 a la cantidad de transacciones utilizadas en el paquete. Si el desarrollador tenía solo 6 transacciones restantes en el paquete actual, ese paquete se llena y el siguiente recuento se incrementa en 4. Se cobrará la tarifa del siguiente paquete, si lo hubiera.

Si el último paquete tiene un límite (no es "ilimitado") y una transacción lo excede, se producen dos situaciones:

Notificaciones ajustables

En el caso de las notificaciones ajustables, se realiza el siguiente cálculo:

custom attribute number = amount added to transaction count

Por ejemplo, si el número de atributo personalizado en el mensaje es 10, se suma 10 a la cantidad total de transacciones.

De qué manera el plan de tarifas obtiene el valor del atributo personalizado

La Política de Grabación de Transacciones (en el paquete de productos de la API) le indica a la monetización en qué parte del mensaje debe buscar el valor del atributo personalizado. El atributo personalizado se define en la sección Custom Attributes de la política de registro de transacciones del paquete de productos de API.

Luego, puedes seleccionar ese atributo personalizado en el plan de tarifas, después de crear un paquete de productos de API que contenga la política de registro de transacciones con el atributo personalizado definido.

Este es el flujo de alto nivel:

  1. Define los atributos personalizados cuando agregues un producto de API.
  2. Cree un paquete de productos de API que contenga el producto.
    En la política de registro de transacciones para el paquete de productos de API, agrega los atributos personalizados que se usarán para definir los planes de tarifas.
  3. Crea un plan de tarifas del tipo de hoja de tarifas o notificación ajustable para el paquete de productos de la API y especifica un parámetro de calificación personalizada.

En la siguiente imagen, se muestra la relación entre el atributo personalizado definido en la política de registro de transacciones y la configuración del plan de hoja de tarifas. La notificación ajustable con la relación de plan de tarifas de atributos personalizados es similar, aunque el valor de bandas de volumen no es aplicable.

Cómo generar el valor del atributo personalizado en el mensaje

La política de registro de transacciones puede buscar el valor del atributo personalizado en varios lugares, como el encabezado de la respuesta, el cuerpo de la respuesta o las variables de flujo predefinidas de la respuesta. (La solicitud no está disponible porque una transacción no es oficial hasta que recibes una respuesta correcta). Los siguientes son ejemplos que muestran cómo agregar un encabezado de respuesta con su valor numérico al mensaje. En ambos casos, se usará la política Asignar mensaje junto con las variables.

Agrega el tamaño de la carga útil de la solicitud al encabezado de respuesta

En cada solicitud de mensaje, hay una variable client.received.content.length que contiene la cantidad de bytes en la carga útil de la solicitud. Si adjuntamos una política de asignación de mensajes a la respuesta del extremo del proxy, podemos generar un encabezado de respuesta llamado messageSize que contenga el valor de longitud:

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

Cómo agregar al encabezado un valor de atributo personalizado de la app

De la misma manera, podemos generar un encabezado con el valor de un atributo personalizado en una app. Por ejemplo, si incluyes un atributo personalizado llamado apprating en cada app de desarrollador, haz lo siguiente:

Cuando se usa la política Verificar clave de API (que es obligatoria para la monetización), este valor se almacena en una variable llamada verifyapikey.{policy_name}.apprating. Con la política de asignación de mensajes adjunta a la respuesta del extremo del proxy, puedes generar un encabezado llamado apprating que contenga el valor apprating de la 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>

Cómo configurar el plan de tarifas

Además de la configuración de atributos personalizados descrita anteriormente, el plan de tarifas se establece de la misma manera que lo harías normalmente (para planes de tarifas sin atributos personalizados), pero debe cumplir con los siguientes requisitos.

Cómo configurar un plan de hoja de tarifas con un atributo personalizado usando la IU

Usa la IU de Edge o la IU clásica de Edge para configurar planes de hojas de tarifas con atributos personalizados, como se describe en las siguientes secciones.

Conexión de integración

Para configurar un plan de hoja de tarifas con atributos personalizados mediante la IU de Edge, sigue estos pasos:

  1. Define los atributos personalizados cuando agregues un producto de API.
  2. Cree un paquete de productos de API que contenga el producto. Consulta Cómo crear paquetes de productos de API.
    En la política de registro de transacciones del paquete de productos de la API, agrega los atributos personalizados que se usarán para definir los planes de tarifas. Para obtener más detalles, consulta la introducción de este tema y Crea una política de registro de transacciones.
  3. Crea un plan de tarifas para el paquete de productos de la API y especifica un parámetro de calificación personalizada.

Para obtener más información, consulta Configura los detalles de los planes de la hoja de tarifas con la IU.

Versión clásica de Edge (nube privada)

Sigue estos pasos para crear una hoja de tarifas con un plan de atributos personalizados mediante la IU clásica de Edge:

  1. En la política de registro de transacciones de un producto de API, agrega los atributos personalizados que se usarán para definir los planes de tarifas. Si deseas obtener más detalles, consulta la introducción de este tema y Crea una política de registro de transacciones. Haz esto para cada producto de API que desees incluir en el paquete de API.
  2. Una vez que los productos de API y las políticas de registro de transacciones estén configurados exactamente como deseas, crea un paquete de API que contenga el producto. Consulta Cómo crear paquetes de API.
  3. Crea un plan de tarifas para el paquete de API y selecciona el tipo de plan de tarifas Hoja de tarifas con atributo personalizado.
  4. Haz clic en el vínculo de hoja de tarifas. Se abrirá la ventana Hoja de tarifas.

  5. Selecciona un atributo personalizado en el menú desplegable Atributo personalizado. El menú enumera los atributos personalizados creados para el producto en una política de registro de transacciones. Se le cobra al desarrollador según el valor del atributo personalizado seleccionado en cada transacción.
    (Valor del atributo * tarifa = cargo al desarrollador)
  6. De manera opcional, configura un plan freemium como se describe en Especifica los detalles del plan de la hoja de tarifas.
  7. Configura un modelo de carga como se describe en Especifica los detalles del plan de la hoja de tarifas. Sin embargo, ten en cuenta que, para el tipo de plan de tarifas de hoja de tarifas con atributos personalizados, el modelo de cobro se basa en el atributo personalizado que selecciones. Por ejemplo, si eliges el modelo de tarifa plana, el desarrollador deberá pagar una tarifa fija según el atributo personalizado, como la cantidad de bytes que se transmiten en cada transacción (no una tarifa fija para cada transacción). Consulta Cálculos para obtener más información.
  8. Haz clic en Save Draft (Guardar borrador).
    Publica el plan solo cuando estés absolutamente seguro de que es definitivo. Consulta Publica planes de tarifas para obtener información sobre cómo configurar la fecha de publicación y cómo publicar el plan.

Para obtener más información, consulta Especifica los detalles del plan de la hoja de tarifas con la IU.

Configura un plan de notificaciones ajustable con atributos personalizados mediante la IU

Configura planes de notificación ajustables con atributos personalizados, como se describe a continuación.

Conexión de integración

Para configurar un plan de hoja de tarifas con atributos personalizados mediante la IU de Edge, sigue estos pasos:

  1. Define los atributos personalizados cuando agregues un producto de API.
  2. Cree un paquete de productos de API que contenga el producto. Consulta Cómo crear paquetes de productos de API.
    En la política de registro de transacciones del paquete de productos de la API, agrega los atributos personalizados que se usarán para definir los planes de tarifas. Para obtener más detalles, consulta la introducción de este tema y Crea una política de registro de transacciones.
  3. Crea un plan de tarifas para el paquete de productos de la API y especifica un parámetro de calificación personalizada.

Si deseas obtener más información, consulta Configura un plan de notificaciones ajustable con la IU.

Versión clásica de Edge (nube privada)

Para configurar un plan de hoja de tarifas con atributos personalizados mediante la IU clásica de Edge, sigue estos pasos:

  1. En la política de registro de transacciones de un producto de API, agrega los atributos personalizados que se usarán para definir los planes de tarifas. Si deseas obtener más detalles, consulta la introducción de este tema y Crea una política de registro de transacciones. Haz esto para cada producto de API que desees incluir en el paquete de API.
  2. Una vez que los productos de API y las políticas de registro de transacciones estén configurados exactamente como deseas, crea un paquete de API que contenga el producto. Consulta Cómo crear paquetes de API.
  3. Crea un plan de tarifas para el paquete de la API y selecciona el tipo de plan de tarifas Notificación ajustable con atributo personalizado.
  4. Haz clic en el vínculo Detalles. Se abrirá la ventana Adjustable Notification.

  5. Selecciona un atributo personalizado en el menú desplegable Atributo personalizado. El menú enumera los atributos personalizados creados para el producto en una política de registro de transacciones. La cantidad total de transacciones del desarrollador se calcula en función del valor del atributo personalizado seleccionado en cada transacción.
  6. Establece la Base de agregación en el período durante el que se agrega el volumen de transacciones. Selecciona un número entre 1 y 24 meses. El valor predeterminado es de 1 mes.
  7. Haz clic en Aplicar y cerrar.
  8. Haz clic en Save Draft (Guardar borrador).
    Publica el plan solo cuando estés absolutamente seguro de que es definitivo. Consulta Publica planes de tarifas para obtener información sobre cómo configurar la fecha de publicación y cómo publicar el plan.

Para obtener más información, consulta Cómo especificar los detalles del plan de notificaciones ajustables mediante la IU.

Especifica los detalles de un plan de tarifas con atributos personalizados mediante la API

Sigue estos pasos de requisitos previos:

  1. En la política de registro de transacciones de un producto de API, agrega los atributos personalizados que se usarán para definir los planes de tarifas. Si deseas obtener más detalles, consulta la introducción de este tema y Crea una política de registro de transacciones. Haz esto para cada producto de API que desees incluir en el paquete de API.
  2. Una vez que los productos de API y las políticas de registro de transacciones estén configurados exactamente como deseas, crea un paquete de API que contenga el producto. Consulta Cómo crear paquetes de API.

A continuación, usa la API para crear el plan de tarifas.

Cuando creas el plan de tarifas con atributos personalizados, especificas los detalles de un plan de tarifas. Debes especificar los detalles en la propiedad ratePlanDetails dentro del cuerpo de la solicitud en una llamada a /organizations/{org_name}/monetization-packages/{package_id}/rate-plans. En los detalles, debes especificar un valor del parámetro de calificación que identifique el nombre del atributo personalizado. También puedes especificar un valor de parámetro de calificación que agregue el atributo personalizado durante un intervalo de tiempo específico.

Consulta la configuración de detalles del plan de tarifas para obtener una lista completa de las opciones detalladas.

Por ejemplo, lo siguiente crea una hoja de tarifas con un plan de atributos personalizados basado en un atributo personalizado llamado messageSize (consulta los elementos en negrita).

$ 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

El siguiente comando crea una notificación ajustable con un plan de tarifas de atributos personalizados basado en un atributo personalizado llamado messageSize (consulta el elemento en negrita).

$ 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