Como gerenciar produtos de API

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Os produtos de API agrupam as APIs e as disponibilizam aos desenvolvedores de apps para consumo. Para ter uma visão geral dos produtos de API, consulte O que é um produto de API?

Como explorar a página de visão geral dos produtos

A página de visão geral Produtos exibe todos os produtos da API e alguns detalhes sobre cada um deles. Nessa página, você pode criar um novo produto de API, excluir um produto ou selecionar um produto para visualizar ou editar.

Para acessar a visão geral dos produtos:

A interface de produtos permite que você execute as seguintes tarefas comuns:

Essas tarefas são descritas nas seções abaixo.

Como criar um produto de API

Esta seção descreve como criar um produto de API usando as interfaces da Apigee.

Para criar um produto da API usando a interface da Apigee:

  1. Se você estiver usando a interface da Apigee no Console do Cloud, selecione Distribuição > Produtos de API. Se você estiver usando a interface clássica da Apigee, selecione Publicar > Produtos da API.
  2. A Apigee exibe a página de visão geral de Produtos.
  3. Clique em Criar. A página de configuração do produto é exibida.
  4. Configure o produto da API. As partes da página de configuração do produto incluem:
    • Detalhes do produto: informações básicas sobre o produto de API, como nome, nível de acesso (particular, público ou interno) e escopos do OAuth.
    • Operações: grupos de proxies de API, caminhos de recursos e métodos HTTP compatíveis com esse produto de API. Também é possível definir limites de cotas para cada operação.
    • Operações de GraphQL: grupos de proxies, caminhos de recursos e tipos de operações GraphQL compatíveis com esse produto de API. Os tipos de operação GraphQL compatíveis incluem consultas e mutações. Você pode especificar um tipo ou o outro ou ambos. Assim como para os proxies de API baseados em REST, é possível definir limites de cota em cada operação.
    • Operações do gRPC: especifique proxies e métodos da API gRPC compatíveis com esse produto da API. Assim como nos proxies de API baseados em REST, é possível definir limites de cota em operações.
    • Atributos personalizados: pares de chave-valor que ajudam a controlar a execução do proxy de API.

    Cada uma dessas partes principais é descrita nas seções abaixo.

  5. Quando terminar, clique em Save. A Apigee cria o novo produto de API. Agora, é possível anexar o produto a um app do desenvolvedor. Consulte Como controlar o acesso às suas APIs registrando apps. Para mais exemplos, consulte Proteger uma API exigindo chaves de API e Proteger uma API com OAuth.

Detalhes do produto

Na seção Detalhes do produto, insira as informações básicas sobre seu novo produto da API. A tabela a seguir descreve os campos desta seção:

Campo Obrigatório? Descrição
Name Obrigatório

Define o nome interno do produto da API. Use esse valor em chamadas à API Apigee que se referem ao produto de API. O valor do campo Name pode incluir caracteres alfanuméricos, espaços e os seguintes caracteres: _ - . # $ %

Por exemplo, My API Product ou my-product.
Display name Obrigatório

Define o nome usado na IU da Apigee para o produto de API. É possível editar o nome de exibição do produto de API a qualquer momento.

O Display name pode incluir caracteres especiais.

Por exemplo, <My> API Product!!!
Description Opcional

É uma string que ajuda a lembrar a finalidade ou a função do produto de API. A descrição pode incluir caracteres especiais.

Por exemplo, The one where I let dev apps read but not write to the "/accounts" endpoints..
Environment Opcional

Identifica para quais ambientes o produto de API permite acesso. Se nenhum ambiente for especificado, todos os ambientes serão permitidos pelo produto de API.

Os ambientes selecionados nesse campo restringem o acesso aos proxies de API com base no local onde eles são implantados. Por exemplo, se o proxy de API A for implantado nos ambientes test e prod, mas o produto de API tiver apenas o ambiente test selecionado, uma chamada de API para o app do desenvolvedor correspondente só permitirá o acesso ao proxy de API A implantado no ambiente test. Para mais informações sobre ambientes, consulte Sobre ambientes e grupos de ambientes.
Access Obrigatório O nível de acesso fornecido aos usuários desse produto de API. Para detalhes, consulte Níveis de acesso.
Automatically approve access requests Opcional (o padrão é selecionado)

Permite a aprovação automática das solicitações de chave que chegam para esse produto de API em qualquer app. Para exigir a aprovação manual da chave, desative essa opção.

O padrão é selecionado, o que significa que esse produto de API aprova automaticamente as solicitações de chave.

Se você selecionar a aprovação manual de chaves, precisará aprovar as solicitações de chaves provenientes de qualquer app que use esse produto de API. Para aprovar manualmente as chaves:

Para mais informações, consulte Como registrar apps e gerenciar chaves de API.
Quota Opcional

Define limites para o número de solicitações permitidas para esse produto de API. Esse valor se aplica à soma de todas as solicitações de operações desse produto de API.

Esse valor é substituído por limites de cota mais específicos definidos nas operações definidas no produto de API.

Inserir um valor de cota não aplica automaticamente as restrições ao número de chamadas que podem ser feitas por meio do produto de API. Você também precisa adicionar a Política de cotas aos proxies de API que são referenciados pelo produto de API.

Para mais informações, consulte Cotas.
Allowed OAuth scope Opcional Se você estiver usando o OAuth com o produto de API, insira uma lista separada por vírgulas de escopos do OAuth que você quer que o produto permita (como "Leitura" ou outros escopos que os aplicativos enviam com suas chamadas de API). Para mais informações, consulte Escopos do OAuth.

Operações

Especifique as operações permitidas em um proxy de API baseado em HTTP, incluindo caminhos de recursos, métodos HTTP e cotas. As operações permitem controlar quais métodos REST têm acesso a quais caminhos de recursos em um produto de API e quantas chamadas podem ser feitas (com a cota).

Para configurar os detalhes da operação, clique em+ ADICIONAR UMA OPERAÇÃO na seção Operações. A visualização Operação é exibida.

Campo Obrigatório? Descrição
API proxy Obrigatório

Selecione o proxy de API para associar a esta operação.
Path Obrigatório

Insira o caminho do recurso para a operação.

É possível usar o caminho da operação para permitir ou proibir solicitações para URIs específicos. Por exemplo, se você definir a origem da operação como o proxy de API music com um caminho base de /music, o produto de API permitirá chamadas para todos os subcaminhos em /music. No entanto, se você quiser que o produto de API permita acesso apenas ao caminho do recurso venues que tem um URI de /music/venues, adicione /venues como o caminho da operação. É possível fazer isso para todas as operações ou para operações específicas.

Nesse caso, as chamadas para /music/venues?name=paramount são permitidas, mas as chamadas para /music/artists?name=Jack%Johnson são bloqueadas.

Observe que há regras especiais para caracteres curinga em caminhos de recursos, conforme descrito em Como configurar caminhos de recursos.
Methods Opcional

Selecione um ou mais métodos de solicitação HTTP na lista suspensa. Esses métodos às vezes são conhecidos como verbos HTTP. A Apigee permite solicitações para o proxy de API que correspondem somente aos métodos selecionados.

O padrão é nenhuma seleção, que permite solicitações com qualquer método HTTP.

Se você não selecionar pelo menos um método, a Apigee inserirá ALL como o valor desse campo quando você salvar a operação.

Para informações sobre a funcionalidade dos métodos de solicitação HTTP, consulte Métodos de solicitação HTTP.
Quota Opcional Especifique os limites de cota para esta operação. Para saber como as cotas são contadas, consulte Noções básicas sobre contadores de cotas.
Custom attributes Opcional Consulte Atributos personalizados.

Operações GraphQL

Para configurar os detalhes da operação GraphQL, clique em + ADICIONAR UMA OPERAÇÃO na seção Operações Graphql. A visualização Operação é exibida. Consulte também Como usar o GraphQL.

Campo Obrigatório? Descrição
API proxy Obrigatório

Selecione o proxy de API para associar a esta operação.
Operation name Obrigatório

Especifique um nome para a operação
Operation type Opcional

Selecione um ou mais tipos de operação GraphQL na lista suspensa. A Apigee permite solicitações ao proxy de API que correspondem apenas aos tipos de operação selecionados.

O padrão é sem seleção, o que permite solicitações com qualquer tipo de operação.

Se você não selecionar pelo menos um tipo, a Apigee inserirá ALL como o valor desse campo quando salvar a operação.

Para informações sobre a funcionalidade dos tipos de operação do GraphQL, consulte Consultas e mutações.
Quota Opcional Especifique os limites de cota para esta operação. Essa cota substitui a cota definida no produto da API. Consulte Cota.
Custom attributes Opcional Consulte Atributos personalizados.

Operações gRPC

Para configurar os detalhes da operação de gRPC, clique em + ADICIONAR UMA OPERAÇÃO, na seção Operações de gRPC. A visualização Operação é exibida. Consulte também Como criar proxies da API gRPC.

Campo Obrigatório? Descrição
API proxy Obrigatório

Selecione o proxy de API para associar a esta operação.
Service name Obrigatório

Especifique um nome para a operação

Na versão atual, não é possível fornecer o nome do servidor de destino. (O nome do serviço e o servidor de destino são os mesmos.)

gRPC methods in service Opcional

Insira os métodos gRPC disponíveis, usando uma lista separada por vírgulas para vários métodos.

Quota Opcional Especifique limites de cota para essas operações. Essa cota substitui a cota definida no produto da API. Consulte Cota.
Custom attributes Opcional Consulte Atributos personalizados.

Atributos personalizados

Os atributos personalizados são pares de chave-valor que podem ser usados de várias maneiras, inclusive ajudando a controlar a execução do proxy de API.

No total, um produto de API pode ter até 18 atributos personalizados, incluindo aqueles definidos em operações.

Por exemplo, é possível criar um atributo personalizado chamado deprecated com um valor de true ou false. No fluxo de proxy de API, é possível verificar o valor do atributo deprecated do produto de API. Se o valor for true, será possível gerar um erro com a política RaiseFault porque você quer que essa operação se comporte como se ela estivesse obsoleta e não fosse mais compatível.

Cota

Define as configurações de cota no proxy da API ou no escopo da operação. Se você definir uma cota, haverá três campos em Quota que precisam ser especificados:

  1. O primeiro campo especifica o número máximo de solicitações permitidas de um app de desenvolvedor para o proxy de API no período especificado.

    Esse campo corresponde ao elemento <Allow> em uma política de cota.

  2. O segundo campo especifica a frequência de redefinição (ou intervalo) da cota.

    Esse campo corresponde ao elemento <Interval> em uma política de cota.

  3. O terceiro campo especifica o tipo de período de redefinição (ou unidade de tempo), como dia, semana ou mês.

    Esse campo corresponde ao elemento <TimeUnit> em uma política de cota.

O exemplo a seguir define um limite de 1.000 solicitações GET, HEAD e TRACE para o proxy de API por dia (todas as outras solicitações HTTP são ignoradas):

Adicionar uma nova cota a uma operação

O exemplo a seguir define um limite de 42 solicitações a cada 3 minutos, independentemente do método HTTP, para o recurso /mypath:

Adicionar uma nova cota a uma operação

Quando você define uma cota para uma operação, é necessário inserir valores para os três campos na seção Cota.

Não é possível definir cotas diferentes para vários métodos HTTP na mesma operação. Para fazer isso, você precisará criar vários produtos de API e definir as cotas específicas do método em cada um.

Se você definir esses valores na Política de cota e no produto de API (na IU, conforme descrito aqui ou com a API Products), a IU do produto de API/APIs terá prioridade.

Como configurar caminhos de recursos

Observe as regras a seguir para caminhos de recursos:

  • /: indica que o caminho base e todos os subcaminhos do caminho base são compatíveis.
  • /**: indica que todos os subcaminhos do caminho base são compatíveis, mas não o caminho base.
  • /*: indica que apenas URIs de um nível abaixo do caminho base são compatíveis.
  • Os caminhos de recursos especificados no produto de API ou nas operações dele se aplicam a todos os proxies de API adicionados ao produto de API.
  • Caminhos de recurso mais inclusivos e menos específicos têm precedência sobre aqueles mais específicos. Por exemplo, se você adicionar / e /**, o caminho do recurso / terá precedência e o caminho do recurso /** será ignorado.

A tabela a seguir mostra o comportamento padrão de um produto de API para diferentes caminhos de recursos. Neste exemplo, o proxy de API tem um caminho base de /v1/weatherapikey. O caminho do recurso do produto da API aplica-se ao sufixo do caminho após o caminho base.

URI de solicitação Permitido para / Permitido para /* Permitido para /** Permitido para /*/2/** Permitido para /*/2/*
/v1/weatherapikey
/v1/weatherapikey/
/v1/weatherapikey/1
/v1/weatherapikey/1/
/v1/weatherapikey/1/2
/v1/weatherapikey/1/2/
/v1/weatherapikey/1/2/3/
/v1/weatherapikey/1/a/2/3/

Por padrão, um caminho de recurso de / em um produto de API é compatível com o caminho base e todos os subcaminhos. Por exemplo, se o caminho de base do proxy de API for /v1/weatherapikey, o produto de API aceitará solicitações para /v1/weatherapikey e para qualquer subcaminho, como /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA e assim por diante.

Com produtos de API, é possível alterar esse padrão para que um caminho de recurso de / corresponda apenas ao caminho base do proxy de API. Isso significa que o produto da API não permitirá acesso a um URI que tenha qualquer coisa depois de /. Se você fizer essa alteração, só seriam permitidas as duas primeiras linhas em "Permitido para /" na tabela acima.

Para mais informações, consulte Como entender a configuração do produto de API.

Como editar um produto de API

Para editar um produto de API:

  1. Se você estiver usando a interface da Apigee no Console do Cloud, selecione Distribuição > Produtos de API. Se você estiver usando a interface clássica da Apigee, selecione Publicar > Produtos da API.
  2. Selecione Publicar > Produtos da API.
  3. Clique na linha do produto de API que você quer editar. A Apigee exibe detalhes sobre o produto de API.
  4. Clique em EDITAR.

  5. Edite as configurações do produto de API, conforme necessário.

    Não é possível editar um recurso de API existente. Em vez disso, você precisará excluir o recurso de API e adicionar uma nova versão com os valores corrigidos, se quiser alterá-lo.

    Será possível excluir um recurso se ele estiver com mau funcionamento ou exigir mais desenvolvimento. Quando excluído, esse recurso não fará mais parte do produto de API atual. Os apps que usam o produto de API não podem mais acessar o recurso excluído. Os recursos excluídos são removidos de um produto de API, mas não do sistema. Dessa forma, eles ainda podem ser usados por outros produtos de API.

  6. (Opcional) Se a monetização da Apigee estiver ativada, crie um plano de tarifas para o produto de API clicando em Adicionar plano de tarifa ou Adicionar (interface clássica).

  7. Clique em Salvar.

As alterações entram em vigor em um curto período (aproximadamente cinco minutos).

Como excluir um produto da API

Antes de excluir um produto de API, é necessário cancelar o registro/desassociar todos os apps de desenvolvedor associados ao produto. Para fazer isso, exclua os apps ou revogue as chaves de API.

Para excluir um produto de API:

  1. Se você estiver usando a interface da Apigee no Console do Cloud, selecione Distribuição > Produtos de API. Se você estiver usando a interface clássica da Apigee, selecione Publicar > Produtos da API.
  2. Selecione Publicar > Produtos da API.
  3. Abra o menu Ações na linha do produto a ser excluído e selecione Excluir.
  4. Depois de confirmar a operação de exclusão, a exclusão entrará em vigor dentro de um curto período (aproximadamente cinco minutos).