Documentação do Oracle Cloud Infrastructure

Criando um Plano de Uso

Descubra como criar um plano de uso como parte de uma estratégia para monitorar e gerenciar o número de solicitações enviadas aos serviços de back-end com o API Gateway.

Como gerente de planos de API, você pode criar planos de uso e assinantes para monitorar e gerenciar o acesso à API e configurar camadas de acesso. Consulte Planos de Uso e Direitos, Assinantes e Tokens do Cliente.

Um plano de uso pode incluir um direito com uma ou mais implantações de API de destino e, opcionalmente, especifica um limite de taxa e uma cota para esse direito. Se o número de solicitações em um determinado período exceder a cota de solicitações do direito, você poderá especificar se as solicitações continuarão sendo permitidas ou se serão rejeitadas. Se uma solicitação for rejeitada porque a cota foi excedida, o cabeçalho de resposta indicará quando a solicitação poderá ser repetida.

Você pode criar um plano de uso que inclua vários direitos, permitindo especificar diferentes limites de taxa e cotas para diferentes implantações de API.

Para que você possa criar um plano de uso, as implantações de API para as quais você está criando o plano de uso já devem existir. Além disso, você já deve ter tornado as implantações de API elegíveis para inclusão no plano de uso (consulte Tornando uma Implantação de API Elegível para Inclusão em um Plano de Uso).

Observe o seguinte:

  • Se um plano de uso contiver um direito a várias implantações de API, qualquer limite de taxa ou cota especificada será compartilhada entre as implantações de API no direito.
  • Um plano de uso não pode conter direitos diferentes que especifiquem um limite de taxa ou cota para a mesma implantação de API. Em outras palavras, uma implantação de API pode ser especificada como um destino em vários direitos em diferentes planos de uso, mas não em vários direitos no mesmo plano de uso.
  • Você pode incluir implantações de API de diferentes gateways de API com o mesmo direito.
  • Se você não especificar um limite de taxa e/ou cota para um direito, um limite de taxa e/ou cota ilimitados se aplicará às implantações de API de destino do direito. Observe que, mesmo que nenhum limite de taxa e/ou nenhuma cota seja especificada para um direito, os clientes de API ainda deverão estar inscritos no plano de uso e ainda deverão informar um token de cliente para acessar as implantações de API de destino.
  • Se você atualizar um plano de uso e alterar o período da cota de um direito para um período diferente (por exemplo, de Dia para Semana), uma nova contagem de números de solicitação será iniciada. No entanto, se você atualizar subsequentemente o plano de uso novamente e alterar o período de tempo da cota de volta para seu valor original, a contagem do número da solicitação anterior será retomada de onde parou (a menos que um novo período tenha começado nesse meio tempo, nesse caso a contagem será redefinida para zero).
  • Depois que uma implantação de API tiver sido incluída em um plano de uso, as solicitações de clientes de API assinados para a implantação de API deverão incluir o token do cliente no local especificado na política de solicitação do plano de uso. Um erro HTTP-403 é retornado em resposta a solicitações que não incluem o token do cliente no local especificado e em resposta a solicitações de clientes de API não assinados.
  • As solicitações que retornam respostas de erro HTTP-4xx contam para a cota de um direito e seu limite de taxa. As solicitações que retornam respostas de erro HTTP-5xx contam para um limite de taxa de direito, mas não para sua cota.
  • No recebimento de solicitações para implantações de API que são incluídas como alvos nos direitos do plano de uso, os gateways de API executam verificações de autenticação e autorização antes de verificar limites e cotas de taxa de direito. As solicitações que falham nas verificações de autenticação e autorização não contam para a cota de um direito ou seu limite de taxa.
  • Você pode criar uma definição de plano de uso que inicialmente não tenha direitos e, em seguida, adicioná-los posteriormente. Observe que, até que você tenha adicionado direitos a uma definição de plano de uso, o plano de uso não poderá ser usado para acessar suas APIs.

Você pode criar um plano de uso:

  • usando a Console
  • usando a CLI e um arquivo JSON

Usando a Console para Criar um Plano de Uso

Para criar um novo plano de uso e um ou mais direitos usando a Console:

  1. Na página da lista Planos de uso, selecione Criar plano de uso. Se precisar de ajuda para localizar a página da lista, consulte Listando Planos de Uso.

  2. Especifique os seguintes valores para o plano de uso:

    • Nome: O nome do novo plano de uso. Por exemplo, Gold-usage-plan. Evite digitar informações confidenciais.
    • Compartimento: o compartimento ao qual pertence o novo plano de uso.
  3. Opcionalmente, selecione Opções Avançadas e especifique:
    • Tags: Se você tiver permissões para criar um recurso, também terá permissões para aplicar tags de formato livre a esse recurso. Para aplicar uma tag definida, você deve ter permissões para usar o namespace da tag. Para obter mais informações sobre tags, consulte Tags de Recursos. Se você não tiver certeza se deseja aplicar tags, ignore essa opção ou pergunte a um administrador. Você pode aplicar tags posteriormente.

  4. Selecione Próximo para especificar as implantações de API que os consumidores de API e clientes de API inscritos no plano de uso têm direito de acessar.

    Um plano de uso compreende direitos. Cada direito especifica uma ou mais implantações de API de destino para as quais os assinantes do plano de uso têm direito de enviar solicitações, juntamente com o número de solicitações que eles têm direito de enviar.

  5. Na página Direitos:

    1. Selecione Criar Direito e especifique detalhes para o primeiro direito do plano de uso:

      • Nome: O nome do novo direito. Os nomes de direito devem ser exclusivos em um plano de uso. Por exemplo, Entitlement1. Evite digitar informações confidenciais.
      • Descrição: Uma descrição do novo direito. Por exemplo, Basic entitlement for all usage plans. Evite digitar informações confidenciais.
      • Limite de Taxa: (Opcional) Selecione Ativar Limite de Taxa para especificar um número máximo de solicitações a serem permitidas por segundo como Solicitações por segundo.
      • Cota: (Opcional) Selecione Ativar Cota para especificar um número máximo de solicitações a serem permitidas em um determinado período:
        • Solicitações: Número máximo de solicitações a serem permitidas.
        • Período: Período ao qual o número máximo de solicitações se aplica. Um dos seguintes: Minuto, Hora, Dia, Semana ou Mês.

        • Redefinir Política: Quando redefinir a contagem do número de solicitações para zero. A política de redefinição do Calendário é suportada. Com a política de redefinição de Calendário, a contagem de números de solicitação é redefinida para zero no início de cada novo período, conforme especificado por Período.

          Por exemplo, se Período estiver definido como Dia, a contagem de números de solicitação será inicialmente definida como zero quando o direito for criado pela primeira vez. A contagem é então redefinida para zero no início do dia seguinte (ou seja, à meia-noite UTC). A contagem é redefinida como zero no início do dia seguinte e assim por diante.

        • Operação em violação: O que acontece se o número máximo de solicitações no período especificado for excedido. Se você especificar Rejeitar, solicitações adicionais no período serão rejeitadas e retornarão uma resposta HTTP-429 Too Many Requests. A resposta inclui o cabeçalho Retry-After, indicando quanto tempo esperar antes de fazer uma nova solicitação. Se você especificar Permitir, solicitações adicionais no período ainda serão permitidas.
      • Implantação Direcionada: Selecione Adicionar Implantação para especificar a primeira implantação de API a ser incluída no direito:
        • Gateway: Selecione o gateway de API no qual a implantação de API foi criada. O gateway de API pode pertencer ao mesmo compartimento do plano de uso, mas não precisa.
        • Implantação: Selecione a implantação de API que você deseja incluir no direito. A implantação de API pode pertencer ao mesmo compartimento do plano de uso, mas não precisa.

          Observe que você já deve ter tornado a implantação de API elegível para inclusão no plano de uso especificando a localização de um token de cliente (consulte Tornando uma Implantação de API Elegível para Inclusão em um Plano de Uso).

        Selecione Salvar para salvar detalhes da primeira implantação de API incluída no direito. Opcionalmente, selecione Adicionar Implantação novamente para especificar implantações de API adicionais a serem incluídas no primeiro direito do plano de uso.

    2. Selecione Salvar para salvar o primeiro direito do plano de uso.
    3. Opcionalmente, selecione Criar Direito novamente e especifique detalhes para direitos adicionais a serem incluídos no plano de uso.
  6. Selecione Próximo para revisar os detalhes informados para o plano de uso.
  7. Selecione Criar para criar o plano de uso.

    Observe que pode levar alguns minutos para criar o novo plano de uso. Enquanto ele está sendo criado, o plano de uso é mostrado com o estado Criando na página Planos de Uso. Quando ele tiver sido criado com sucesso, o novo plano de uso será mostrado com um estado Ativo.

    Observe também que, em vez de criar o novo plano de uso imediatamente, você pode criá-lo posteriormente usando o Resource Manager e o Terraform, selecionando Salvar como pilha para salvar a definição de recurso como uma configuração do Terraform. Para obter mais informações sobre como salvar pilhas de definições de recursos, consulte Criando uma Pilha de uma Página de Criação de Recurso.

  8. Se você tiver aguardado mais de alguns minutos para que o plano de uso seja mostrado com um estado Ativo (ou se a operação de criação do plano de uso tiver falhado):

    1. Selecione o nome do plano de uso e selecione Solicitações de Serviço para ver uma visão geral da operação de criação do plano de uso.
    2. Selecione a operação Criar Plano de Uso para ver mais informações sobre a operação (incluindo mensagens de erro, mensagens de log e o status de recursos associados).
    3. Se a operação de criação do plano de uso tiver falhado e você não puder diagnosticar a causa do problema com base nas informações da solicitação de serviço, consulte Solução de Problemas do Serviço API Gateway.

Usando a CLI e um Arquivo JSON para Criar um Plano de Uso

Para criar um novo plano de uso e um ou mais direitos usando a CLI:

  1. Usando seu editor de JSON preferido, crie um arquivo de definição de plano de uso no 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": {}
}
    em que:
    • "displayName": "<usage-plan-name>" é o nome do novo plano de uso. Por exemplo, "displayName": "Gold-usage-plan". Evite digitar informações confidenciais.
    • "entitlements": [{...}] especifica detalhes de um ou mais direitos, em que:
      • "name": "<entitlement-name>" é o nome de um novo direito. Os nomes dos direitos devem ser exclusivos dentro de um plano de uso. Por exemplo, "Entitlement1". Evite digitar informações confidenciais.
      • "description": "<entitlement-description>" é uma descrição do novo direito. Por exemplo, "description": "Basic entitlement for all usage plans". Evite digitar informações confidenciais..
      • "rateLimit": {…} especifica opcionalmente um número máximo de solicitações a serem permitidas por segundo. Se você definir um limite de taxa, deverá incluir valores para todos os itens a seguir:
        • "value": <rate-limit-value> é o número máximo de solicitações a serem permitidas. Por exemplo, "value": 100.
        • "unit": "<rate-limit-unit>" é a unidade de tempo do limite de taxa. Deve ser definido como "SECOND".
      • "quota": {…} especifica opcionalmente um número máximo de solicitações a serem permitidas em um determinado período. Se você definir uma cota, deverá incluir valores para todos os itens a seguir:
        • "value": <quota-value> é o número máximo de solicitações a serem permitidas por período. Por exemplo, "value": 1000
        • "unit": "<quota-unit>" é o período ao qual o número máximo de solicitações se aplica. Deve ser definido como MINUTE, HOUR, DAY, WEEK ou MONTH. Por exemplo, "unit": "MONTH".
        • "resetPolicy": "CALENDAR" é quando a contagem do número de solicitações é redefinida para zero. A política de redefinição CALENDAR é suportada. Com a política de redefinição CALENDAR, a contagem de números de solicitação é redefinida como zero no início de cada novo período, conforme especificado por "unit".

          Por exemplo, se "unit": "DAY", a contagem do número da solicitação será inicialmente definida como zero quando o direito for criado pela primeira vez. A contagem é redefinida para zero no início do dia seguinte (ou seja, à meia-noite UTC). A contagem é redefinida para zero no início do dia seguinte e assim por diante.

        • "operationOnBreach": "<REJECT|ALLOW>" especifica o que acontecerá se o número máximo de solicitações no período da cota for excedido. Se você especificar REJECT, solicitações adicionais no período serão rejeitadas e retornarão uma resposta HTTP-429 Too Many Requests. A resposta inclui o cabeçalho Retry-After, indicando quanto tempo esperar antes de fazer uma nova solicitação. Se você especificar ALLOW, solicitações adicionais no período ainda serão permitidas. Por exemplo, "operationOnBreach": "REJECT"
      • "targets": [{…}] especifica uma ou mais implantações de API de destino que os assinantes do plano de uso têm direito de acessar, em que:
        • "deploymentId": "<target-deployment-ocid>" é o OCID da implantação de API que você deseja incluir no direito. A implantação de API pode pertencer ao mesmo compartimento do plano de uso, mas não precisa. Por exemplo, "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"

          Observe que você já deve ter tornado a implantação de API elegível para inclusão no plano de uso especificando a localização de um token de cliente (consulte Tornando uma Implantação de API Elegível para Inclusão em um Plano de Uso).

    • "compartmentId": "<compartment-ocid>" é o OCID do compartimento ao qual o novo plano de uso pertence. Por exemplo, "ocid1.compartment.oc1..aaaaaaaa7______ysq"

    Por exemplo:

    {
    "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. Salve o arquivo de definição do plano de uso com um nome de sua escolha. Por exemplo, gold-usageplan.json
  3. Use o arquivo de definição do plano de uso para criar um plano de uso usando a CLI:
    1. Configure seu ambiente de cliente para usar a CLI ( Configurando Seu Ambiente de Cliente para usar a CLI para o Desenvolvimento de Gateway de API).

    2. Abra um prompt de comando e execute oci api-gateway usage-plan create para criar o plano de uso com base no arquivo de definição do plano de uso:

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

      em que:

      • --from-json file://<usageplan-definition>.json é o arquivo que contém a definição do plano de uso, incluindo um caminho.

      Por exemplo:

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

      A resposta ao comando inclui:

      • O OCID do plano de uso e outros detalhes.
      • O estado do ciclo de vida (por exemplo, ACTIVE, FAILED).
      • O ID da solicitação de serviço para criar o plano de uso (Detalhes das solicitações de serviço estão disponíveis por sete dias após a conclusão, o cancelamento ou a falha).

      Se quiser que o comando aguarde o retorno de controle até que o plano de uso esteja ativo (ou a solicitação tenha falhado), inclua um ou ambos os seguintes parâmetros:

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

      Por exemplo:

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

      Observe que não é possível usar o plano de uso até que a solicitação de serviço o tenha criado com sucesso e o plano de uso esteja ativo.

    3. (Opcional) Para ver o status do plano de uso, informe:

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

    4. (Opcional) Para ver o status da solicitação de serviço que está criando o plano de uso, informe:

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

    5. (Opcional) Para exibir os logs da solicitação de serviço que está criando o plano de uso, informe:

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

    6. (Opcional) Se a solicitação de serviço que está criando o plano de uso falhar e você quiser revisar os logs de erro, informe:

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

    Para obter mais informações sobre o uso da CLI, consulte Interface de Linha de Comando (CLI). Para obter uma lista completa de flags e opções disponíveis para comandos da CLI, consulte a Ajuda da CLI.