Documentación de Oracle Cloud Infrastructure

Creación de un suscriptor

Descubra cómo crear un suscriptor 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 suscriptores para sus clientes (consumidores de API) para especificar los planes de uso que les otorgan acceso a sus API. Consulte Planes de uso y derechos, suscriptores y tokens de cliente.

Una definición de suscriptor incluye nombres de cliente y tokens de cliente para identificar de forma única a los clientes de API y especifica los planes de uso que les otorgan acceso a sus API.

Tenga en cuenta que:

  • Para poder crear un suscriptor, debe existir al menos uno de los planes de uso a los que desea que se suscriba el suscriptor (consulte Creación de un Plan de Uso).
  • Si define un suscriptor y especifica varios clientes de API para él, el límite de frecuencia y la cuota en el derecho de un plan de uso se comparten entre todos los clientes de API.
  • Una vez creado un suscriptor, puede agregar y eliminar clientes y cambiar tokens de cliente.
  • El token de cliente que especifique para un cliente de API en una definición de suscriptor está diseñado solo para fines de generación de informes del plan de uso. No utilice este token para la autenticación y autorización del cliente de API. En su lugar, utilice funciones de autorizador o tokens web JSON (JWT) para la autenticación y autorización del cliente de API. Consulte Agregación de autenticación y autorización a despliegues de API.
  • Si aparece un despliegue de API en más de uno de los planes de uso a los que está suscrito un suscriptor, se utiliza el primer plan de uso de la lista de planes de uso suscritos para acceder al despliegue de API. Puede cambiar el orden de la lista de planes de uso suscritos.
  • Si un suscriptor está suscrito a un plan de uso y desea suscribirlo a un nuevo plan de uso, Oracle le recomienda que realice la operación en dos pasos. Para empezar, agregue el nuevo plan de uso a la definición de suscriptor como primer plan de uso en la lista de planes de uso suscritos y guarde el cambio. A continuación, elimine el plan de uso anterior de la lista de planes de uso suscritos y guarde el cambio.
  • Puede crear una definición de suscriptor que inicialmente no tenga clientes de API ni planes de uso de destino y, a continuación, agregarlos más tarde. Tenga en cuenta que hasta que no haya agregado clientes de API y planes de uso de destino a una definición de suscriptor, el suscriptor no podrá acceder a sus API.

Puede crear un suscriptor:

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

Uso de la consola para crear un suscriptor

Para crear un nuevo suscriptor y suscribirlo a uno o más planes de uso mediante la consola:

  1. En la página de lista Suscriptores, seleccione Crear suscriptor. Si necesita ayuda para buscar la página de lista, consulte Listado de suscriptores.

  2. Especifique los siguientes valores para el suscriptor:

    • Nombre: el nombre del nuevo suscriptor. Por ejemplo, Premium-subscriber. Evite introducir información confidencial.
    • Compartimento: compartimento al que pertenece el nuevo suscriptor.
    • Clientes: uno o más clientes de API que accederán a despliegues de API mediante los planes de uso a los que está suscrito el suscriptor. Para cada cliente de API, especifique:
      • Nombre: nombre que se elige para el cliente de API. Los nombres de cliente deben ser únicos en un suscriptor. Por ejemplo, android. Recomendación: especifique un nombre significativo porque puede proporcionarlo a los consumidores de API para la recopilación y el análisis de datos del plan de uso.
      • Token: cadena de caracteres de su elección para identificar de forma única el cliente de API. El token que especifique debe ser único en su arrendamiento para la región actual y no debe tener más de 128 caracteres. Por ejemplo, abc123def456ghi789jkl. Si ya no existe ningún identificador adecuado, seleccione Generar token para crear uno.
        Nota

        El token que especifique para un cliente de API en una definición de suscriptor está destinado solo a fines de generación de informes del plan de uso. No utilice este token para la autenticación y autorización del cliente de API. En su lugar, utilice funciones de autorizador o tokens web JSON (JWT) para la autenticación y autorización del cliente de API. Consulte Agregación de autenticación y autorización a despliegues de API.
    • Planes de uso: seleccione Agregar plan de uso para suscribir al suscriptor a uno o más planes 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 Crear para crear el suscriptor.

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

    Tenga en cuenta también que, en lugar de crear el nuevo suscriptor inmediatamente, puede crearlo más tarde mediante Resource Manager y Terraform, seleccionando Guardar como pila para guardar la definición del 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.

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

    1. Seleccione el nombre del suscriptor y seleccione Solicitudes de trabajo para ver una visión general de la operación de creación de suscriptor.
    2. Seleccione Crear suscriptor 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 suscriptor 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 suscriptor

Para crear un suscriptor nuevo y suscribirse a uno o más planes de uso mediante la CLI:

  1. Con su editor de JSON preferido, cree un archivo de definición de suscriptor con el formato:
    {
    "displayName": "<subscriber-name>",
    "clients": [
        {"name": "<api-client-name-one>", "token": "<unique-identifier>"}
    ],
    "usagePlans": ["<usage-plan-ocid>"],
    "compartmentId": "<compartment-ocid>",
    "freeformTags": {},
    "definedTags": {}
}
    donde:
    • "displayName": "<subscriber-name>" es el nombre del nuevo suscriptor. Por ejemplo, "displayName": "Premium-subscriber". Evite introducir información confidencial.
    • "clients": [{...}] especifica uno o más clientes de API que accederán a despliegues de API mediante los planes de uso a los que está suscrito el suscriptor. Para cada cliente de API, especifique:
      • "name": "<api-client-name>" es el nombre que elija para el cliente de API. Los nombres de cliente deben ser únicos en un suscriptor. Por ejemplo, "name": "android". Recomendación: especifique un nombre significativo porque puede proporcionarlo a los consumidores de API para la recopilación y el análisis de datos del plan de uso. Evite introducir información confidencial.
      • "token": "<unique-identifier>" es una cadena de caracteres de su elección para identificar de forma única el cliente de API. El token que especifique debe ser único en su arrendamiento para la región actual y no debe tener más de 128 caracteres. Por ejemplo, "token": "abc123def456ghi789jkl".
        Nota

        El token que especifique para un cliente de API en una definición de suscriptor está destinado solo a fines de generación de informes del plan de uso. No utilice este token para la autenticación y autorización del cliente de API. En su lugar, utilice funciones de autorizador o tokens web JSON (JWT) para la autenticación y autorización del cliente de API. Consulte Agregación de autenticación y autorización a despliegues de API.
    • "usagePlans": [{…}] especifica el OCID de uno o más planes de uso a los que suscribir el suscriptor. El plan de uso puede pertenecer al mismo compartimento que el suscriptor, pero no tiene que hacerlo. Por ejemplo, "usagePlans": "ocid1.usageplan.oc1..aaaaaaaaab______gap".
    • "compartmentId": "<compartment-ocid>" es el OCID del compartimento al que pertenece el nuevo suscriptor. Por ejemplo, "ocid1.compartment.oc1..aaaaaaaa7______ysq"

    Por ejemplo:

    {
    "displayName": "MySubscriber",
    "clients": [
        {"name": "android", "token": "XXXXXX"},
        {"name": "iOS", "token": "YYYYYY"}
    ],
    "usagePlans": ["ocid1.usageplan.oc1..aaaaaaaaab______gap", "ocid1.usageplan.oc1..aaaaaaaaab______eya"],
    "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
    "freeformTags": {},
    "definedTags": {}
}
  2. Guarde el archivo de definición de suscriptor con el nombre que desee. Por ejemplo, premium-subscriber.json
  3. Utilice el archivo de definición de suscriptor para crear un suscriptor 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 subscriber create para crear el suscriptor a partir del archivo de definición de suscriptor:

      oci api-gateway subscriber create --from-json file://<subscriber-definition>.json

      donde:

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

      Por ejemplo:

      oci api-gateway subscriber create --from-json file://premium-subscriber.json

      La respuesta al comando incluye:

      • OCID del suscriptor y otros detalles.
      • Estado del ciclo de vida (por ejemplo, ACTIVE, FAILED).
      • ID de la solicitud de trabajo para crear el suscriptor (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 suscriptor 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 subscriber create --from-json file://premium-subscriber.json --wait-for-state ACTIVE

      Tenga en cuenta que no puede utilizar el suscriptor hasta que la solicitud de trabajo la haya creado correctamente y el suscriptor esté activo.

    3. (Opcional) Para ver el estado del suscriptor, escriba:

      oci api-gateway subscriber get --subscriber-id <subscriber-ocid>

    4. (Opcional) Para ver el estado de la solicitud de trabajo que está creando el suscriptor, 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 suscriptor, 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 suscriptor 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.