Documentación de Oracle Cloud Infrastructure

Creación de un plan de uso

Descubra cómo crear un plan de uso como parte de una estrategia para supervisar y gestionar el número de solicitudes enviadas a servicios de backend con API Gateway.

Como gestor de planes de API, puede crear planes de uso y suscriptores para supervisar y gestionar el acceso de API y configurar niveles de acceso. Consulte Planes de uso y derechos, suscriptores y tokens de cliente.

Un plan de uso puede incluir un derecho con uno o más despliegues de API de destino y, opcionalmente, especifica un límite de ratio y una cuota para ese derecho. Si el número de solicitudes en un período de tiempo determinado supera la cuota de solicitud del derecho, puede especificar si las solicitudes se siguen permitiendo o se rechazan. Si se rechaza una solicitud porque se ha superado la cuota, la cabecera de respuesta indica cuándo se puede intentar la solicitud.

Puede crear un plan de uso que incluya varios derechos, lo que le permitirá especificar diferentes límites de frecuencia y cuotas para diferentes despliegues de API.

Para poder crear un plan de uso, los despliegues de API para los que está creando el plan de uso ya deben existir. Además, ya debe haber hecho que los despliegues de API sean elegibles para su inclusión en el plan de uso (consulte Elegibilidad de un despliegue de API para su inclusión en un plan de uso).

Tenga en cuenta que:

  • Si un plan de uso contiene un derecho a varios despliegues de API, cualquier límite de frecuencia o cuota que especifique se compartirá entre los despliegues de API en el derecho.
  • Un plan de uso no puede contener derechos diferentes que especifiquen un límite de frecuencia o una cuota para el mismo despliegue de API. En otras palabras, un despliegue de API se puede especificar como destino en varios derechos en diferentes planes de uso, pero no en varios derechos en el mismo plan de uso.
  • Puede incluir despliegues de API de diferentes gateways de API en el mismo derecho.
  • Si no especifica un límite de cuota y/o cuota para un derecho, se aplica un límite de cuota y/o cuota ilimitados a los despliegues de API de destino del derecho. Tenga en cuenta que, aunque no se especifique ningún límite de frecuencia ni cuota para un derecho, los clientes de API deben seguir suscritos al plan de uso y deben transferir un token de cliente para acceder a los despliegues de API de destino.
  • Si actualiza un plan de uso y cambia el período de tiempo de cuota de un derecho a un período de tiempo diferente (por ejemplo, de día a semana), se inicia un nuevo recuento de números de solicitud. Sin embargo, si posteriormente vuelve a actualizar el plan de uso y cambia el período de tiempo de cuota a su valor original, el recuento de números de solicitud anterior se reanuda desde donde lo dejó (a menos que haya comenzado un nuevo período de tiempo mientras tanto, en cuyo caso el recuento se restablece a cero).
  • Una vez que se ha incluido un despliegue de API en un plan de uso, las solicitudes de los clientes de API suscritos al despliegue de API deben incluir el token de cliente en la ubicación especificada en la política de solicitud del plan de uso. Se devuelve un error HTTP-403 en respuesta a solicitudes que no incluyen el token de cliente en la ubicación especificada y en respuesta a solicitudes de clientes de API no suscritos.
  • Las solicitudes que devuelven respuestas de error HTTP-4xx cuentan tanto para la cuota de un derecho como para su límite de frecuencia. Las solicitudes que devuelven respuestas de error HTTP-5xx cuentan para el límite de frecuencia de un derecho, pero no para su cuota.
  • Al recibir solicitudes de despliegues de API que se incluyen como destinos en los derechos del plan de uso, los gateways de API realizan comprobaciones de autenticación y autorización antes de comprobar las cuotas y los límites de ratio de derechos. Las solicitudes que fallan en las comprobaciones de autenticación y autorización no cuentan para la cuota de un derecho ni para su límite de frecuencia.
  • Puede crear una definición de plan de uso que inicialmente no tenga derechos y, a continuación, agregarlos más tarde. Tenga en cuenta que hasta que haya agregado derechos a una definición de plan de uso, el plan de uso no se puede utilizar para acceder a las API.

Puede crear un plan de uso:

  • uso de la consola
  • uso de la CLI y un archivo JSON

Uso de la consola para crear un plan de uso

Para crear un nuevo plan de uso y uno o más derechos mediante la consola:

  1. En la página de lista Planes de uso, seleccione Crear plan de uso. Si necesita ayuda para buscar la página de lista, consulte Listado de planes de uso.

  2. Especifique los siguientes valores para el plan de uso:

    • Nombre: nombre del nuevo plan de uso. Por ejemplo, Gold-usage-plan. Evite introducir información confidencial.
    • Compartimento: compartimento al que pertenece el nuevo plan de uso.
  3. Opcionalmente, seleccione Opciones avanzadas y especifique:
    • Etiquetas: si tiene permisos para crear un recurso, también tiene permisos para aplicar etiquetas de formato libre a ese recurso. Etiquetas Para aplicar una etiqueta definida, debe tener permisos para utilizar el espacio de nombres de etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.

  4. Seleccione Siguiente para especificar los despliegues de API a los que tienen derecho los consumidores de API y los clientes de API suscritos al plan de uso.

    Un plan de uso incluye derechos. Cada derecho especifica uno o más despliegues de API de destino a los que los suscriptores al plan de uso tienen derecho a enviar solicitudes, junto con el número de solicitudes que tienen derecho a enviar.

  5. En la página Derechos:

    1. Seleccione Crear derecho y especifique los detalles del primer derecho del plan de uso:

      • Nombre: el nombre del nuevo derecho. Los nombres de derechos deben ser únicos dentro de un plan de uso. Por ejemplo, Entitlement1. Evite introducir información confidencial.
      • Descripción: descripción del nuevo derecho. Por ejemplo, Basic entitlement for all usage plans. Evite introducir información confidencial.
      • Límite de frecuencia: (opcional) seleccione Activar límite de frecuencia para especificar un número máximo de solicitudes para permitir por segundo como Solicitudes por segundo.
      • Cuota: (opcional) seleccione Activar cuota para especificar un número máximo de solicitudes para permitir en un período de tiempo determinado:
        • Solicitudes: número máximo de solicitudes que se permiten.
        • Período: período al que se aplica el número máximo de solicitudes. Uno de los siguientes: Minuto, Hora, Día, Semana o Mes.

        • Restablecer política: cuándo restablecer el recuento del número de solicitudes a cero. Se admite la política de restablecimiento de Calendario. Con la política de restablecimiento de Calendario, el recuento de números de solicitud se restablece a cero al inicio de cada nuevo período de tiempo, como se especifica en Período.

          Por ejemplo, si Periodo se define en Día, el recuento de números de solicitud se define inicialmente en cero cuando se crea el derecho por primera vez. A continuación, el recuento se restablece a cero al inicio del día siguiente (es decir, a medianoche, UTC). El recuento se restablece a cero al inicio del día siguiente, etc.

        • Operación con incumplimiento: qué sucede si se supera el número máximo de solicitudes en el período de tiempo especificado. Si especifica Rechazar, se rechazan las solicitudes adicionales en el período de tiempo y se devuelve una respuesta HTTP-429 Too Many Requests. La respuesta incluye la cabecera Retry-After, que indica cuánto tiempo se debe esperar antes de realizar una nueva solicitud. Si especifica Permitir, aún se permiten solicitudes adicionales en el período de tiempo.
      • Despliegue de destino: seleccione Agregar despliegue para especificar el primer despliegue de API que se va a incluir en el derecho:
        • Gateway: seleccione el gateway de API en el que se ha creado el despliegue de API. El gateway de API puede pertenecer al mismo compartimento que el plan de uso, pero no tiene que hacerlo.
        • Despliegue: seleccione el despliegue de API que desea incluir en el derecho. El despliegue de API puede pertenecer al mismo compartimento que el plan de uso, pero no tiene que hacerlo.

          Tenga en cuenta que ya debe haber hecho que el despliegue de API sea elegible para su inclusión en el plan de uso especificando la ubicación de un token de cliente (consulte Elegibilidad de un despliegue de API para la inclusión en un plan de uso).

        Seleccione Guardar para guardar los detalles del primer despliegue de API incluido en el derecho. Opcionalmente, vuelva a seleccionar Agregar despliegue para especificar despliegues de API adicionales para incluir en el primer derecho del plan de uso.

    2. Seleccione Guardar para guardar el primer derecho del plan de uso.
    3. Opcionalmente, vuelva a seleccionar Crear derecho y especifique los detalles de los derechos adicionales que desea incluir en el plan de uso.
  6. Seleccione Siguiente para revisar los detalles introducidos para el plan de uso.
  7. Seleccione Crear para crear el plan de uso.

    Tenga en cuenta que la creación del nuevo plan de uso puede tardar unos minutos. Mientras se crea, el plan de uso se muestra con el estado Creando en la página Planes de uso. Una vez que se ha creado correctamente, el nuevo plan de uso se muestra en estado Activo.

    Tenga en cuenta también que, en lugar de crear el nuevo plan de uso inmediatamente, puede crearlo más tarde mediante Resource Manager y Terraform, seleccionando Guardar como pila para guardar la definición de recurso como una configuración de Terraform. Para obtener más información sobre cómo guardar pilas de definiciones de recursos, consulte Creación de una pila a partir de una página de creación de recursos.

  8. Si ha esperado más de unos minutos para que el plan de uso se muestre con el estado Activo (o si la operación de creación del plan de uso ha fallado):

    1. Seleccione el nombre del plan de uso y seleccione Solicitudes de trabajo para ver una visión general de la operación de creación del plan de uso.
    2. Seleccione Crear plan de uso para obtener más información sobre esta operación (incluidos los mensajes de error, los mensajes de log y el estado de los recursos asociados).
    3. Si la operación de creación de plan de uso ha fallado y no puede diagnosticar la causa del problema a partir de la información de la solicitud de trabajo, consulte Solución de problemas de gateway de API.

Uso de la CLI y un archivo JSON para crear un plan de uso

Para crear un nuevo plan de uso y uno o más derechos mediante la CLI:

  1. Mediante el uso de su editor JSON preferido, cree un archivo de definición de plan de uso con el formato:
    {
    "displayName": "<usage-plan-name>",
    "entitlements": [{
        "name": "<entitlement-name>",
        "description": "<entitlement-description>",
        "rateLimit": {
            "value": <rate-limit-value>,
            "unit": "<rate-limit-unit>"
        },
        "quota": {
            "value": <quota-value>,
            "unit": "<quota-unit>",
            "resetPolicy": "CALENDAR",
            "operationOnBreach": "<REJECT|ALLOW>"
        },
        "targets": [{
            "deploymentId": "<target-deployment-ocid>"
        }]
    }],
    "compartmentId": "<compartment-ocid>",
    "freeformTags": {},
    "definedTags": {}
}
    donde:
    • "displayName": "<usage-plan-name>" es el nombre del nuevo plan de uso. Por ejemplo, "displayName": "Gold-usage-plan". Evite introducir información confidencial.
    • "entitlements": [{...}] especifica los detalles de uno o más derechos, donde:
      • "name": "<entitlement-name>" es el nombre de un nuevo derecho. Los nombres de derechos deben ser únicos dentro de un plan de uso. Por ejemplo, "Entitlement1". Evite introducir información confidencial.
      • "description": "<entitlement-description>" es una descripción del nuevo derecho. Por ejemplo, "description": "Basic entitlement for all usage plans". Evite introducir información confidencial..
      • "rateLimit": {…} especifica opcionalmente un número máximo de solicitudes para permitir por segundo. Si define un límite de frecuencia, debe incluir valores para lo siguiente:
        • "value": <rate-limit-value> es el número máximo de solicitudes que se permiten. Por ejemplo, "value": 100.
        • "unit": "<rate-limit-unit>" es la unidad de tiempo del límite de velocidad. Se debe definir en "SECOND".
      • "quota": {…} especifica opcionalmente un número máximo de solicitudes para permitir en un período de tiempo determinado. Si define una cuota, debe incluir valores para todo lo siguiente:
        • "value": <quota-value> es el número máximo de solicitudes que se permiten por período de tiempo. Por ejemplo, "value": 1000
        • "unit": "<quota-unit>" es el período de tiempo al que se aplica el número máximo de solicitudes. Se debe definir en uno de los valores MINUTE, HOUR, DAY, WEEK o MONTH. Por ejemplo, "unit": "MONTH".
        • "resetPolicy": "CALENDAR" es cuando el recuento del número de solicitudes se restablece a cero. La política de restablecimiento CALENDAR está soportada. Con la política de restablecimiento CALENDAR, el recuento de números de solicitud se restablece a cero al inicio de cada nuevo período de tiempo, según lo especificado por "unit".

          Por ejemplo, si "unit": "DAY", el recuento de números de solicitud se define inicialmente en cero cuando se crea el derecho por primera vez. El recuento se restablece a cero al inicio del día siguiente (es decir, a medianoche UTC). El recuento se restablece a cero al inicio del día siguiente, etc.

        • "operationOnBreach": "<REJECT|ALLOW>" especifica lo que sucede si se supera el número máximo de solicitudes en el período de tiempo de la cuota. Si especifica REJECT, las solicitudes adicionales en el período de tiempo se rechazan y devuelven una respuesta HTTP-429 Too Many Requests. La respuesta incluye la cabecera Retry-After, que indica cuánto tiempo se debe esperar antes de realizar una nueva solicitud. Si especifica ALLOW, se seguirán permitiendo solicitudes adicionales en el período de tiempo. Por ejemplo, "operationOnBreach": "REJECT"
      • "targets": [{…}] especifica uno o más despliegues de API de destino a los que los suscriptores del plan de uso tienen derecho de acceso, donde:
        • "deploymentId": "<target-deployment-ocid>" es el OCID del despliegue de API que desea incluir en el derecho. El despliegue de API puede pertenecer al mismo compartimento que el plan de uso, pero no tiene que hacerlo. Por ejemplo, "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"

          Tenga en cuenta que ya debe haber hecho que el despliegue de API sea elegible para su inclusión en el plan de uso especificando la ubicación de un token de cliente (consulte Elegibilidad de un despliegue de API para la inclusión en un plan de uso).

    • "compartmentId": "<compartment-ocid>" es el OCID del compartimento al que pertenece el nuevo plan de uso. Por ejemplo, "ocid1.compartment.oc1..aaaaaaaa7______ysq"

    Por ejemplo:

    {
    "displayName": "Gold-usage-plan",
    "entitlements": [{
        "name": "Entitlement1",
        "description": "Basic entitlement for all usage plans",
        "rateLimit": {
            "value": 100,
            "unit": "SECOND"
        },
        "quota": {
            "value": 1000,
            "unit": "MONTH",
            "resetPolicy": "CALENDAR",
            "operationOnBreach": "REJECT"
        },
        "targets": [{
            "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
        }]
    },
    {
        "name": "Entitlement2",
        "description": "Gold plan entitlement",
        "rateLimit": {
            "value": 200,
            "unit": "SECOND"
        },
        "quota": {
            "value": 5000,
            "unit": "WEEK",
            "resetPolicy": "CALENDAR",
            "operationOnBreach": "REJECT"
        },
        "targets": [{
            "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
          },
          {
            "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaac______nxd"
          }
        ]
      }
    ],
    "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq"
}
  2. Guarde el archivo de definición del plan de uso con el nombre que desee. Por ejemplo, gold-usageplan.json
  3. Use el archivo de definición de plan de uso para crear un plan de uso mediante la CLI:
    1. Configure su entorno de cliente para usar la CLI ( Configuración del entorno de cliente para utilizar la CLI para el desarrollo de gateway de API).

    2. Abra un símbolo del sistema y ejecute oci api-gateway usage-plan create para crear el plan de uso a partir del archivo de definición del plan de uso:

      oci api-gateway usage-plan create --from-json file://<usageplan-definition>.json

      donde:

      • --from-json file://<usageplan-definition>.json es el archivo que contiene la definición del plan de uso, incluida una ruta de acceso.

      Por ejemplo:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json

      La respuesta al comando incluye:

      • OCID del plan de uso y otros detalles.
      • Estado del ciclo de vida (por ejemplo, ACTIVE, FAILED).
      • ID de la solicitud de trabajo para crear el plan de uso (los detalles de las solicitudes de trabajo están disponibles durante siete días tras la finalización, cancelación o fallo).

      Si desea que el comando espere para devolver el control hasta que el plan de uso esté activo (o hasta que la solicitud falle), incluya uno o los dos parámetros siguientes:

      • --wait-for-state ACTIVE
      • --wait-for-state FAILED

      Por ejemplo:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json --wait-for-state ACTIVE

      Tenga en cuenta que no puede usar el plan de uso hasta que la solicitud de trabajo lo haya creado correctamente y el plan de uso esté activo.

    3. (Opcional) Para ver el estado del plan de uso, introduzca:

      oci api-gateway usage-plan get --usage-plan-id <usage-plan-ocid>

    4. Para ver el estado de la solicitud de trabajo que está creando el plan de uso, introduzca:

      oci api-gateway work-request get --work-request-id <work-request-ocid>

    5. (Opcional) Para ver los logs de la solicitud de trabajo que está creando el plan de uso, introduzca:

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>

    6. (Opcional) Si falla la solicitud de trabajo que está creando el plan de uso y desea revisar los logs de errores, introduzca:

      oci api-gateway work-request-error --work-request-id <work-request-ocid>

    Para obtener más información sobre el uso de la CLI, consulte Interfaz de línea de comandos (CLI). Para obtener una lista completa de los indicadores y las opciones disponibles para los comandos de la CLI, consulte Ayuda de CLI.