Documentação do Oracle Cloud Infrastructure

Criando um Assinante

Descubra como criar um assinante 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 assinantes para seus clientes (consumidores de API) para especificar os planos de uso que lhes dão acesso às suas APIs. Consulte Planos de Uso e Direitos, Assinantes e Tokens do Cliente.

Uma definição de assinante inclui nomes de clientes e tokens de clientes para identificar exclusivamente clientes de API e especifica os planos de uso que lhes dão acesso às suas APIs.

Observe o seguinte:

  • Para poder criar um assinante, pelo menos um dos planos de uso para os quais você deseja que o assinante se inscreva já deve existir (consulte Criando um Plano de Uso).
  • Se você definir um assinante e especificar vários clientes de API para ele, o limite de taxa e a cota no direito de um plano de uso serão compartilhados entre todos os clientes de API.
  • Depois de criar um assinante, você pode subsequentemente adicionar e remover clientes e alterar tokens de cliente.
  • O token do cliente especificado para um cliente de API em uma definição de assinante destina-se apenas para fins de relatório do plano de uso. Não use esse token para autenticação e autorização do cliente de API. Em vez disso, use funções de autorizador ou JWTs (JSON Web Tokens) para autenticação e autorização do cliente de API. Consulte Adicionando Autenticação e Autorização às Implantações de API.
  • Se uma implantação de API aparecer em mais de um dos planos de uso aos quais um assinante está inscrito, o primeiro plano de uso na lista de planos de uso assinados será usado para acessar a implantação de API. Você pode alterar a ordem da lista de planos de uso assinados.
  • Se um assinante estiver inscrito em um plano de uso e você quiser inscrever o assinante em um novo plano de uso, a Oracle recomenda que você execute a operação em duas etapas. Para começar, adicione o novo plano de uso à definição do assinante como o primeiro plano de uso na lista de planos de uso assinados e salve a alteração. Em seguida, remova o plano de uso anterior da lista de planos de uso assinados e salve a alteração.
  • Você pode criar uma definição de assinante que inicialmente não tenha clientes de API e/ou planos de uso de destino e, em seguida, adicioná-los posteriormente. Observe que, até que você tenha adicionado clientes de API e planos de uso de destino a uma definição de assinante, o assinante não poderá acessar suas APIs.

Você pode criar um assinante:

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

Usando a Console para Criar um Assinante

Para criar um novo assinante e assiná-lo em um ou mais planos de uso usando a Console:

  1. Na página da lista Assinantes, selecione Criar assinante. Se precisar de ajuda para localizar a página da lista, consulte Listando Assinantes.

  2. Especifique os seguintes valores para o assinante:

    • Nome: O nome do novo assinante. Por exemplo, Premium-subscriber. Evite digitar informações confidenciais.
    • Compartimento: O compartimento ao qual o novo assinante pertence.
    • Clientes: Um ou mais clientes de API que acessarão implantações de API usando os planos de uso nos quais o assinante está inscrito. Para cada cliente de API, especifique:
      • Nome: Um nome de sua escolha para o cliente de API. Os nomes de cliente devem ser exclusivos em um assinante. Por exemplo, android. Recomendação: Especifique um nome significativo porque você pode fornecê-lo aos consumidores de API para fins de coleta e análise de dados do plano de uso.
      • Token: Uma string de caracteres de sua escolha para identificar exclusivamente o cliente da API. O token especificado deve ser exclusivo na sua tenancy para a região atual e não deve ter mais de 128 caracteres. Por exemplo, abc123def456ghi789jkl. Se nenhum identificador adequado já existir, selecione Gerar Token para criar um.
        Observação

        O token especificado para um cliente de API em uma definição de assinante destina-se apenas para fins de relatório do plano de uso. Não use esse token para autenticação e autorização do cliente de API. Em vez disso, use funções de autorizador ou JWTs (JSON Web Tokens) para autenticação e autorização do cliente de API. Consulte Adicionando Autenticação e Autorização às Implantações de API.
    • Planos de Uso: Selecione Adicionar Plano de Uso para inscrever o assinante em um ou mais planos 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 Criar para criar o assinante.

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

    Observe também que, em vez de criar o novo assinante 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.

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

    1. Selecione o nome do assinante e selecione Solicitações de Serviço para ver uma visão geral da operação de criação do assinante.
    2. Selecione a operação Criar Assinante 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 assinante 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 Assinante

Para criar um novo assinante e assiná-lo em um ou mais planos de uso usando a CLI:

  1. Usando seu editor de JSON preferido, crie um arquivo de definição de assinante no formato:
    {
    "displayName": "<subscriber-name>",
    "clients": [
        {"name": "<api-client-name-one>", "token": "<unique-identifier>"}
    ],
    "usagePlans": ["<usage-plan-ocid>"],
    "compartmentId": "<compartment-ocid>",
    "freeformTags": {},
    "definedTags": {}
}
    em que:
    • "displayName": "<subscriber-name>" é o nome do novo assinante. Por exemplo, "displayName": "Premium-subscriber". Evite digitar informações confidenciais.
    • "clients": [{...}] especifica um ou mais clientes de API que acessarão implantações de API usando os planos de uso aos quais o assinante está inscrito. Para cada cliente de API, especifique:
      • "name": "<api-client-name>" é o nome de sua escolha para o cliente de API. Os nomes de cliente devem ser exclusivos em um assinante. Por exemplo, "name": "android". Recomendação: Especifique um nome significativo porque você pode fornecê-lo aos consumidores de API para fins de coleta e análise de dados do plano de uso. Evite digitar informações confidenciais.
      • "token": "<unique-identifier>" é uma string de caracteres de sua escolha para identificar exclusivamente o cliente da API. O token especificado deve ser exclusivo em sua tenancy para a região atual e não deve ter mais de 128 caracteres. Por exemplo, "token": "abc123def456ghi789jkl".
        Observação

        O token especificado para um cliente de API em uma definição de assinante destina-se apenas para fins de relatório do plano de uso. Não use esse token para autenticação e autorização do cliente de API. Em vez disso, use funções de autorizador ou JWTs (JSON Web Tokens) para autenticação e autorização do cliente de API. Consulte Adicionando Autenticação e Autorização às Implantações de API.
    • "usagePlans": [{…}] especifica o OCID de um ou mais planos de uso para os quais se inscrever o assinante. O plano de uso pode pertencer ao mesmo compartimento do assinante, mas não precisa. Por exemplo, "usagePlans": "ocid1.usageplan.oc1..aaaaaaaaab______gap".
    • "compartmentId": "<compartment-ocid>" é o OCID do compartimento ao qual o novo assinante pertence. Por exemplo, "ocid1.compartment.oc1..aaaaaaaa7______ysq"

    Por exemplo:

    {
    "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. Salve o arquivo de definição de assinante com um nome de sua escolha. Por exemplo, premium-subscriber.json
  3. Use o arquivo de definição de assinante para criar um assinante 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 subscriber create para criar o assinante a partir do arquivo de definição de assinante:

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

      em que:

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

      Por exemplo:

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

      A resposta ao comando inclui:

      • O OCID do assinante e outros detalhes.
      • O estado do ciclo de vida (por exemplo, ACTIVE, FAILED).
      • O ID da solicitação de serviço para criar o assinante (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 assinante 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 subscriber create --from-json file://premium-subscriber.json --wait-for-state ACTIVE

      Observe que você não pode usar o assinante até que a solicitação de serviço a tenha criado com sucesso e o assinante esteja ativo.

    3. (Opcional) Para ver o status do assinante, informe:

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

    4. (Opcional) Para ver o status da solicitação de serviço que está criando o assinante, 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 assinante, 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 assinante 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.