Introdução

Esta é a documentação da Apigee X.
Veja a documentação da Apigee Edge.

As seções a seguir apresentam os produtos da API e conceitos relacionados, como cotas e chaves de API.

O que é um produto de API?

Como provedor de API, você cria produtos de API para agrupar suas APIs e disponibilizá-las para o consumo dos desenvolvedores de aplicativos. Pense nos produtos de API como sua linha de produtos.

Especificamente, um produto de API agrupa uma ou mais operações. Uma operação especifica um proxy de API e os caminhos de recursos que podem ser acessados nesse proxy. Uma operação também pode limitar o acesso por métodos HTTP e por cota.

Os produtos de API são o principal mecanismo de controle de acesso às suas APIs. Ao definir um ou mais produtos de API em um aplicativo do desenvolvedor, é possível restringir o acesso a proxies com uma chave de API. Na Apigee, as chaves de API são provisionadas, não para as próprias APIs, mas para produtos de API. Em outras palavras, as chaves de API são provisionadas para pacotes de operações que definem uma linha de produtos ou um plano de serviços específico.

Casos de uso comuns

Você pode criar vários produtos de API que contenham operações para tratar de casos de uso específicos. Por exemplo, é possível criar um produto de API que agrupe várias operações que contenham recursos de mapeamento para permitir que os desenvolvedores integrem facilmente mapas nos seus aplicativos.

Além disso, é possível usar produtos de API para definir níveis de preço com base em critérios como:

O número de solicitações:

  • Premium: solicitações ilimitadas por dia
  • Básico: até 1.000 solicitações por dia
  • Grátis: até 100 solicitações por dia

Ou nível de acesso:

  • Premium: leitura, gravação, atualização e exclusão
  • Básico: leitura e atualização
  • Grátis: somente leitura

Ou qualquer combinação desses itens:

  • Premium extra: leitura e gravação ilimitadas por dia
  • Premium: leitura e gravação de até 1.000 solicitações por dia
  • Básico: acesso de leitura e gravação até 100 vezes por dia
  • Gratuito: leitura até 1.000 vezes por dia
  • Gratuito: acesso somente leitura limitado a 100 solicitações por dia

Operações

Uma operação é um grupo de atributos que restringem o acesso a um ou mais proxies de API com base em critérios como caminho do recurso, método HTTP e cota. Uma operação inclui estes atributos:

Atributo Obrigatório? Descrição
Proxy de API Obrigatório Cada grupo de operações precisa especificar um proxy de API. Apenas um proxy é permitido por grupo de operações.
Serviço remoto Depende Obrigatório apenas se você instalar e planejar usar o adaptador da Apigee para o Envoy.
Caminho do recurso Obrigatório Cada grupo de operações precisa especificar um ou mais caminhos de recurso. Os caminhos de recursos em uma operação restringem o acesso a recursos específicos em um proxy de API. (Um caminho do recurso é a parte do URL de solicitação do proxy de API que vem depois do caminho de base do proxy.)
Método HTTP Opcional Você também pode restringir o acesso a um proxy pelo método HTTP. Por exemplo, se você especificar os métodos GET e POST para um grupo de operações, somente as solicitações HTTP GET e POST poderão acessar o proxy para o caminho do recurso especificado. Se nenhum método for especificado, todos os métodos serão permitidos.
Cota Opcional É possível especificar uma cota para o grupo de operações. A cota especificada em um grupo de operações tem precedência sobre uma cota no nível do produto da API, se especificada.
Atributos personalizados Opcional Os atributos personalizados são úteis para métricas, monitoramento ou casos em que você quer armazenar informações extras com um produto de API que pode ser acessado ou recuperado posteriormente. Os atributos personalizados associados a uma operação existem além de todos os atributos personalizados no nível do produto da API e podem ser acessados no ambiente de execução como variáveis de fluxo com o prefixo apiproduct.operation.attributes.

Chaves de API

Quando você registra o aplicativo de um desenvolvedor na sua organização, o aplicativo precisa estar associado a pelo menos um produto de API. Como resultado do pareamento de um aplicativo com um ou mais produtos de API, a Apigee atribui ao aplicativo uma chave única de consumidor. Consulte também Como registrar aplicativos e gerenciar chaves.

A chave de consumidor ou o token de acesso funciona como credenciais de solicitação. O desenvolvedor de aplicativos incorpora a chave do consumidor no aplicativo, de modo que, quando o aplicativo faz uma solicitação a uma API hospedada pela Apigee, o aplicativo transmite a chave do consumidor na solicitação de uma das seguintes maneiras:

  • Quando a API usa a verificação de chaves de API, o app precisa transmitir a chave do consumidor diretamente.
  • Quando a API usa a verificação de token OAuth, o aplicativo precisa transmitir um token derivado da chave do consumidor.

A aplicação da chave de API não acontece automaticamente. Usando a chave do consumidor ou os tokens OAuth como credenciais de solicitação, o proxy da API valida as credenciais de solicitação nos proxies da API incluindo uma política VerifyAPIKey ou uma configuração de política VerifyAccessToken (consulte política OAuthv2) no fluxo apropriado. Se você não incluir uma política de aplicação de credenciais no Proxy de API, qualquer autor da chamada poderá invocar suas APIs.

Para verificar as credenciais transmitidas na solicitação, a Apigee executa as seguintes etapas:

  1. Recebe as credenciais transmitidas com a solicitação. No caso da verificação do token OAuth, a Apigee verifica se o token não está expirado e procura a chave do consumidor usada para gerar o token.
  2. Recupere a lista de produtos de API a que a chave do consumidor foi associada.
  3. Confirme se o proxy atual da API está incluído no produto da API, se o caminho do recurso atual (caminho do URL) está ativado no produto da API e, se estiver incluído no produto, se a solicitação usa um verbo HTTP especificado.
  4. Verifique se a cota, se especificada, não foi excedida.
  5. Verifique se a chave do consumidor não expirou ou foi revogada. Confira também se o app não está revogado e se o desenvolvedor está ativo.

Se todas as verificações acima forem aprovadas, a verificação de credencial será bem-sucedida.

Em suma, a Apigee gera automaticamente chaves de consumidor, mas os editores de API precisam aplicar a verificação de chaves nos proxies de API usando as políticas apropriadas.

Aprovação de chaves

Por padrão, todas as solicitações para conseguir uma chave para acessar um produto de API de um aplicativo são aprovadas automaticamente. Como alternativa, é possível configurar o produto de API para que você aprove as chaves manualmente. Essa configuração é descrita em Como adicionar um produto de API. Nesse caso, você precisará aprovar as solicitações principais de qualquer aplicativo que adicione o produto de API. Para mais informações, consulte Registrar aplicativos e gerenciar chaves de API.

Cotas

As cotas podem proteger os servidores de back-end contra variações de tráfego altas e diferenciar a linha de produtos. Por exemplo, você pode agrupar recursos com uma cota alta como um produto premium e usar o mesmo pacote com uma cota menor como produto básico. As cotas podem ajudar a evitar que os servidores fiquem sobrecarregados se um produto for popular e receber uma grande quantidade de solicitações em um curto período.

É possível especificar uma cota que se aplica a todos os proxies de API incluídos no produto de API ou especificar cotas no nível da operação. Uma cota especificada em uma operação tem prioridade sobre uma cota definida no nível do produto da API.

A definição de limites de cota em um produto de API não aplica a cota automaticamente. Trata-se apenas de um limite padrão que pode ser referenciado nas políticas de cota. Veja algumas vantagens de definir uma cota no produto para políticas de cotas para referência:

  • Use uma política de cotas para aplicar uma configuração uniforme em todos os proxies de API em um produto de API.
  • Se você alterar as configurações de cota do produto da API no ambiente de execução, as políticas de cota farão referência automaticamente às configurações de cota atualizadas.

Para ver mais informações, consulte os seguintes tópicos:

Escopos do OAuth

Defina os escopos do OAuth como uma lista separada por vírgulas que precisa estar presente nos tokens de acesso associados ao produto. Para mais informações sobre o uso de escopos com as políticas OAuth da Apigee, consulte Como trabalhar com escopos do OAuth2.

Níveis de acesso

Ao definir um produto de API, é possível estabelecer os seguintes níveis de acesso:

Nível de acesso Descrição
Public Produtos de API disponíveis para todos os desenvolvedores. Você pode adicioná-los aos portais do desenvolvedor integrados ou baseados em Drupal.
Private ou Internal only Produtos de API criados para uso particular ou interno.

Para o portal integrado, é possível adicionar produtos da API Private ou Internal only e disponibilizá-los aos desenvolvedores de aplicativos, conforme necessário.

Para portais de desenvolvedores baseados no Drupal, é possível gerenciar o acesso aos produtos de API Private ou Internal only no seu portal do desenvolvedor, conforme descrito nas seções a seguir:

  • Para os portais do desenvolvedor Drupal 8/9, configure o acesso aos produtos de API Private ou Internal only no portal do desenvolvedor, conforme descrito em Configurar permissões de acesso aos produtos da API:
  • Nos portais do desenvolvedor do Drupal 7, não é possível adicionar produtos de API Private ou Internal only ao portal de desenvolvedor.

    Para disponibilizar produtos de API Private e Internal only a desenvolvedores de aplicativos, é necessário adicioná-los manualmente a um aplicativo registrado pela IU ou API da Apigee, conforme descrito em Registrar aplicativos e gerenciar chaves de API.

    Depois de adicionado, o desenvolvedor verá o produto de API associado ao aplicativo no seu portal, conforme descrito em Como gerenciar produtos de API em um aplicativo. Se o desenvolvedor do aplicativo desativar o acesso a um produto de API Private ou Internal only, ele será removido do app e precisará ser adicionado manualmente pelo administrador do portal.