Esta página foi traduzida pela API Cloud Translation.

Publicar APIs usando a API Edge

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Nesta seção, descrevemos como usar a API Edge para criar produtos de API para publicação em portais de desenvolvedores.

Criar produtos de API usando a API

Com os produtos de API, os desenvolvedores podem registrar apps que consomem APIs usando chaves de API e tokens de acesso OAuth. Os produtos de API foram projetados para permitir que você "empacote" recursos da API e, em seguida, publique esses pacotes em diferentes grupos de desenvolvedores. Por exemplo, talvez seja necessário publicar um conjunto de recursos de API nos desenvolvedores parceiros enquanto publica outro pacote para desenvolvedores externos. Os produtos de API permitem executar esse pacote rapidamente, sem exigir nenhuma alteração nas suas próprias APIs. Um benefício extra é que é possível fazer "upgrade" ou "downgrade" do acesso do desenvolvedor sem que os desenvolvedores precisem receber novas chaves do cliente para os aplicativos.

Para criar um produto de API usando a API, emita uma solicitação POST para /organizations/{org_name}/apiproducts. Para mais informações, consulte a referência de API Criar produto de API.

A solicitação a seguir cria um produto de API chamado weather_free. O produto da API fornece acesso a todas as APIs expostas pelo proxy de API chamado weatherapi que é implantado no ambiente test. O tipo de aprovação é definido como auto, indicando que qualquer solicitação de acesso será aprovada.

curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \
-H "Content-Type:application/json" \
-d \
'{
  "approvalType": "auto",
  "displayName": "Free API Product",
  "name": "weather_free",
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ]
}' \
-u email:password

Exemplo de resposta:

{
  "apiResources" : [ ],
  "approvalType" : "auto",
  "attributes" : [ ],
  "createdAt" : 1362759663145,
  "createdBy" : "developer@apigee.com",
  "displayName" : "Free API Product",
  "environments" : [ "test" ],
  "lastModifiedAt" : 1362759663145,
  "lastModifiedBy" : "developer@apigee.com",
  "name" : "weather_free",
  "proxies" : [ "weatherapi" ],
  "scopes" : [ ]
}

O produto de API criado acima implementa o cenário mais básico, autorizando solicitações a um proxy de API em um ambiente. Ele define um produto de API que permite que um app autorizado acesse qualquer recurso de API acessado por meio do proxy de API em execução no ambiente de teste. Os produtos de API expõem configurações extras que permitem personalizar o controle de acesso às APIs para diferentes grupos de desenvolvedores. Por exemplo, é possível criar dois produtos de API que fornecem acesso a diferentes proxies de API. Também é possível criar dois produtos de API que fornecem acesso aos mesmos proxies de API, mas com diferentes configurações de cota associadas.

Configurações de produto de API

Os produtos de API expõem as seguintes opções de configuração:

Nome	Descrição	Padrão	Obrigatório?
`apiResources`	Uma lista de URIs separados por vírgulas ou caminhos de recursos agrupados no produto de API. Por padrão, os caminhos de recursos são mapeados da variável `proxy.pathsuffix`. O sufixo do caminho do proxy é o fragmento de URI após o caminho base do ProxyEndpoint. Por exemplo, na amostra de produto de API abaixo, o elemento `apiResources` é definido como `/forecastrss`. Como o caminho base definido para esse proxy de API é `/weather`, isso significa que apenas solicitações para `/weather/forecastrss` são permitidas por este produto de API. É possível selecionar um caminho específico ou usar um caractere curinga para selecionar todos os subcaminhos. Os caracteres curinga (/** e /) são compatíveis. O caractere curinga de asterisco duplo indica que todos os subURIs estão incluídos. Um único asterisco indica que apenas URIs de um nível abaixo são incluídos. Por padrão, '/' é compatível com os mesmos recursos de '/*' e com o caminho base definido pelo proxy da API. Por exemplo, se o caminho base do proxy da API for /v1/weatherapikey, o produto da API aceita solicitações para /v1/weatherapikey e qualquer subURI, como /v1/weatherapikey/predictionrss, /v1/weatherapikey/region/CA e assim por diante. Consulte Gerenciar produtos da API para mais informações sobre como alterar o comportamento desse padrão.	N/D	Não
`approvalType`	Especifica como as chaves de API são aprovadas para acessar as APIs definidas pelo produto de API. Se definida como `manual`, a chave gerada para o app ficará no estado "pendente". Essas chaves só funcionarão após serem explicitamente aprovadas. Se definido como `auto`, todas as chaves serão aprovadas no momento da criação e funcionarão imediatamente. `auto` é normalmente usado para fornecer acesso a produtos de API gratuitos/de avaliação que fornecem cotas ou recursos limitados.	N/D	Sim
`attributes`	Matriz de atributos que pode ser usada para estender o perfil de produto da API padrão com metadados específicos do cliente. Use essa propriedade para especificar o nível de acesso do produto de API como público, particular ou interno. Exemplo: "attributes": [ { "name": "access", "value": "public" }, { "nome": "foo", "value": "foo" }, { "name": "bar", "value": "bar" } ]	N/D	Não
`scopes`	Uma lista separada por vírgulas de escopos OAuth validados no ambiente de execução. (Apigee Edge) valida se os escopos em qualquer token de acesso apresentado correspondem ao escopo definido na API product.)	N/A	Não
`proxies`	Proxies de API nomeados a que o produto de API está vinculado. Ao especificar proxies, é possível associar recursos do produto de API a proxies de API específicos, impedindo que os desenvolvedores acessem esses recursos por outros proxies de API.	N/D	Não. Se não for definido, `apiResources` precisará ser definido explicitamente (consulte as informações de `apiResources` acima) e a variável `flow.resource.name` definida na política AssignMessage.
`environments`	Ambientes nomeados (por exemplo, "test" ou "prod") a que esse produto de API está vinculado. Ao especificar um ou mais ambientes, é possível vincular os recursos listados no produto da API a um ambiente específico, impedindo que o desenvolvedor acesse esses recursos por proxies de API de outro ambiente. Esta configuração é usada, por exemplo, para impedir que recursos associados a proxies de API em "prod" sejam acessados por proxies de API implantados em "test".	N/D	Não. Se não for definido, `apiResources` precisará ser explicitamente definido e a variável `flow.resource.name` definida na política AssignMessage.
`quota`	Número de solicitações permitidas por app durante o intervalo de tempo especificado.	N/D	Não
`quotaInterval`	Número de unidades de tempo em que as cotas são avaliadas	N/D	Não
`quotaTimeUnit`	A unidade de tempo (minuto, hora, dia ou mês) utilizada para contar cotas.	N/D	Não

Veja a seguir um exemplo mais detalhado para criar um produto de API.

curl -X POST  https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-H "Content-Type:application/json" -d \
'{
  "apiResources": [ "/forecastrss" ],
  "approvalType": "auto", 
  "attributes":
    [ {"name": "access", "value": "public"} ],
  "description": "Free API Product",
  "displayName": "Free API Product",
  "name": "weather_free",
  "scopes": [],
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ],
  "quota": "10",
  "quotaInterval": "2",
  "quotaTimeUnit": "hour" }' \
-u email:password

Exemplo de resposta

{
  "apiResources" : [ "/forecastrss" ],
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "access",
    "value" : "public"
  },
  "createdAt" : 1344454200828,
  "createdBy" : "admin@apigee.com",
  "description" : "Free API Product",
  "displayName" : "Free API Product",
  "lastModifiedAt" : 1344454200828,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "weather_free",
  "scopes" : [ ],
  "proxies": [ {'weatherapi'} ],
  "environments": [ {'test'} ],
  "quota": "10",
  "quotaInterval": "1",
  "quotaTimeUnit": "hour"}'
}

Sobre escopos

Um escopo é um conceito do OAuth que é similar ao conceito de "permissão". Ativado Os escopos do Apigee Edge são totalmente opcionais. Os escopos podem ser usados para conseguir uma autorização mais detalhada. Todas as chaves de cliente emitidas a um aplicativo são associadas a um "escopo principal". O escopo principal é o conjunto de todos os escopos em todos os produtos de API referentes a esse aplicativo. Para aplicativos aprovados para consumir vários produtos de API, o escopo principal é a união de todos os escopos definidos nos produtos de API para que a chave do cliente foi aprovada.

Ver produtos de API

Para ver produtos de API criados para uma organização que usa a API, consulte as seguintes seções:

Ver produtos de API (monetizados)
Por padrão, apenas os produtos de API que geram receita são exibidos (ou seja, produtos de API com pelo menos um plano de preços publicado). Para exibir todos os produtos de API, defina o parâmetro de consulta monetized como false. Isso equivale a emitir uma solicitação GET para os produtos de API não monetizados da API List: https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true
Ver produtos de API (não monetizados)
Visualizar produtos de API qualificados para um desenvolvedor
Visualizar produtos de API qualificados para uma empresa

Veja a seguir um exemplo de como visualizar produtos de API usando a API:

curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
  -H "Accept:application/json" \
  -u email:password

A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):

{
  "product" : [ {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "payment api product",
    "displayName" : "payment",
    "id" : "payment",
    "name" : "payment",
    "organization" : {
      ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  }, {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "messaging api product",
    "displayName" : "messaging",
    "id" : "messaging",
    "name" : "messaging",
    "organization" : ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  } ],
  "totalRecords" : 2
}

Registrar desenvolvedores usando a API

Todos os aplicativos pertencem a desenvolvedores ou empresas. Portanto, para criar um app, primeiro você precisa registrar um desenvolvedor ou empresa.

Os desenvolvedores são registrados em uma organização pela criação de um perfil. Observe que o desenvolvedor e-mail incluído no perfil é usado como a chave exclusiva para o desenvolvedor em todo Apigee Edge.

Para oferecer compatibilidade com a monetização, você precisa definir os atributos de monetização ao criar ou editar desenvolvedores. Também é possível definir outros tipos atributos para uso em análises personalizadas, aplicação de políticas personalizadas e assim por diante; essas regras arbitrárias atributos não serão interpretados pelo Apigee Edge,

Por exemplo, a solicitação a seguir registra um perfil de um desenvolvedor com endereço de e-mail ntesla@theremin.com e define um subconjunto de monetização usando a API Create developer:

$ curl -H "Content-type:application/json" -X POST -d \
'{"email" : "ntesla@theremin.com", 
  "firstName" : "Nikola", 
  "lastName" : "Tesla", 
  "userName" : "theremin", 
  "attributes" : [ 
  { 
    "name" : "project_type", 
    "value" : "public"
  },
  {    
   "name": "MINT_BILLING_TYPE",
   "value": "POSTPAID"
  },
  {
   "name": "MINT_DEVELOPER_ADDRESS",
   "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
  },
  {
   "name": "MINT_DEVELOPER_TYPE",
   "value": "TRUSTED"
  },
  {    
   "name": "MINT_HAS_SELF_BILLING,
   "value": "FALSE"
  },
  {
   "name" : "MINT_SUPPORTED_CURRENCY",
   "value" : "usd"
  }
 ] 
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
-u email:password

Exemplo de resposta

{
          "email" : "ntesla@theremin.com",
          "firstName" : "Nikola",
          "lastName" : "Tesla",
          "userName" : "theremin",
          "organizationName" : "{org_name}",
          "status" : "active",
          "attributes" : [ 
          {
            "name" : "project_type",
            "value" : "public"
          },
          {    
             "name": "MINT_BILLING_TYPE",
             "value": "POSTPAID"
          },
          {
             "name": "MINT_DEVELOPER_ADDRESS",
             "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
          },
          {
             "name": "MINT_DEVELOPER_TYPE",
             "value": "TRUSTED"
          },
          {    
             "name": "MINT_HAS_SELF_BILLING,
             "value": "FALSE"
          },
          {
             "name" : "MINT_SUPPORTED_CURRENCY",
             "value" : "usd"
          } 
          ],
          "createdAt" : 1343189787717,
          "createdBy" : "admin@apigee.com",
          "lastModifiedAt" : 1343189787717,
          "lastModifiedBy" : "admin@apigee.com"
        }

Registrar apps de desenvolvedor usando a API

Todo app registrado no Apigee Edge está associado a um desenvolvedor e a um produto de API. Quando um app é registrado em nome de um desenvolvedor, o Apigee Edge gera uma "credencial" (uma chave do cliente e par secreto) que identifica o app. Em seguida, o app precisa transmitir essas credenciais como parte de todas as solicitações para um produto de API associado ao app.

A solicitação a seguir usa o botão Criar Developer App para registrar um app para o desenvolvedor criado acima: ntesla@theremin.com. Ao registrar um app, você define um nome para ele, um callbackUrl e uma lista de uma ou mais APIs produtos:

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "weather_free"], 
  "callbackUrl" : "login.weatherapp.com", 
  "keyExpiresIn" : "2630000000",
  "name" : "weatherapp"}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
-u email:password

O callbackUrl é usado por alguns tipos de concessão de OAuth (como código de autorização) para validar solicitações de redirecionamento do aplicativo. Se você usar o OAuth, esse valor precisará ser igual ao valor de redirect_uri usado para fazer solicitações OAuth.

O atributo keyExpiresIn especifica, em milissegundos, a vida útil da chave do cliente que será gerada para o aplicativo para desenvolvedor. O valor padrão, -1, indica um período de validade infinito.

Exemplo de resposta

{
  "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1",
  "attributes": [
    {
      "name": "DisplayName",
      "value": "Test Key Expires"
    },
    {
      "name": "Notes",
      "value": "Just testing this attribute"
    }
  ],
  "createdAt": 1421770824390,
  "createdBy": "wwitman@apigee.com",
  "credentials": [
    {
      "apiProducts": [
        {
          "apiproduct": "ProductNoResources",
          "status": "approved"
        }
      ],
      "attributes": [],
      "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt",
      "consumerSecret": "AX7lGGIRJs6s8J8y",
      "expiresAt": 1424400824401,
      "issuedAt": 1421770824401,
      "scopes": [],
      "status": "approved"
    }
  ],
  "developerId": "e4Oy8ddTo3p1BFhs",
  "lastModifiedAt": 1421770824390,
  "lastModifiedBy": "wwitman@apigee.com",
  "name": "TestKeyExpires",
  "scopes": [],
  "status": "approved"
}

Gerenciar chaves de cliente para apps usando a API

Encontrar a chave do cliente (a chave de API) do aplicativo

As credenciais de um aplicativo (produto de API, chave do cliente e secret) são retornadas como parte do perfil do aplicativo. Um administrador de uma organização pode recuperar a chave do cliente a qualquer momento.

O perfil de aplicativo exibe o valor da chave de cliente e o secret, o status da chave de cliente e qualquer associação de produtos de API referente à chave. Como administrador, é possível recuperar o perfil da chave de cliente a qualquer momento usando a API para ver detalhes importantes de um app para desenvolvedores:

$ curl -X GET -H "Accept: application/json" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Exemplo de resposta

{
  "apiProducts" : [ {
    "apiproduct" : "weather_free",
    "status" : "approved"
  } ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Consulte Ver detalhes importantes de um app para desenvolvedores para mais informações.

Adicionar um produto de API a um aplicativo e uma chave

Para atualizar um app e adicionar um novo produto de API, adicione o produto de API à chave do app usando a API para adicionar produto de API à chave. Consulte Adicionar produto de API à chave para mais informações.

Adicionar um produto de API a uma chave de aplicativo permite que o aplicativo com a chave acesse os recursos da API agrupados no produto de API. A chamada de método a seguir adiciona um novo produto de API a um app:

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "newAPIProduct"]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Exemplo de resposta:

{
  "apiProducts": [
   {
     "apiproduct": "weather_free",
     "status": "approved"
   },
   {
     "apiproduct": "newAPIProduct",
     "status": "approved"
   }
 ],
 "attributes": [],
 "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
 "consumerSecret": "1eluIIdWG3JGDjE0",
 "expiresAt": -1,
 "issuedAt": 1411491156464,
 "scopes": [],
 "status": "approved"
 }

Aprovar chaves de cliente

Definir o tipo de aprovação como manual permite que você controle quais desenvolvedores podem acessar os recursos protegidos por produtos da API. Quando os produtos de API tiverem a aprovação definida como manual, as chaves de cliente precisarão ser aprovadas explicitamente. As chaves podem ser aprovadas explicitamente usando a API para aprovar ou revogar chave específica de app para desenvolvedor:

$ curl -X POST -H "Content-type:appilcation/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
-u email:password

Exemplo de resposta

{
  "apiProducts" : [ {
  "apiproduct" : "weather_free",
  "status" : "approved"
} ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Consulte Aprovar ou revogar chave específica de app para desenvolvedores para mais informações.

Aprovar produtos de API para chaves de cliente

A associação de um produto de API com uma chave de cliente também tem um status. Para que o acesso à API seja bem-sucedido, a chave de cliente precisa ser aprovada e a chave de cliente precisa ser aprovada para o produto de API apropriado. A associação de uma chave de cliente com um produto de API pode ser aprovada usando a API para aprovar ou revogar produto de API referente a uma chave de app para desenvolvedor:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
-u email:password

Esse comando cURL não retorna uma resposta. Consulte Aprovar ou revogar produto de API de uma chave referente a um aplicativo para desenvolvedor para saber mais.

Revogar produtos de API para chaves de cliente

Há muitos motivos para revogar a associação de uma chave de cliente com um produto de API. Talvez seja necessário remover um produto de API de uma chave de cliente devido ao não pagamento pelo desenvolvedor, um período de avaliação expirado ou quando um app for promovido de um produto de API para outro.

Para revogar a associação de uma chave de cliente com um produto de API, use a API para aprovar ou revogar chave específica de app para desenvolvedor, usando a ação de revogação na chave de cliente do app para desenvolvedor:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
-u email:password

Esse comando cURL não retorna uma resposta. Consulte Aprovar ou revogar chave específica de app para desenvolvedores para mais informações.

Aplicar configurações de produto de API

Para que os produtos de API sejam aplicados, um dos seguintes tipos de política precisa ser anexado ao fluxo de proxy de API:

VerifyAPIKey: recebe uma referência a uma chave de API, verifica se ela representa um app válido e corresponde ao produto de API. Consulte Verificar a política da chave de API para mais informações.
OAuthV1, operação "VerifyAccessToken": verifica a assinatura, valida um token de acesso do OAuth 1.0a e uma "chave do cliente", e corresponde o aplicativo ao produto da API. Consulte a política do OAuth v1.0 para saber mais.
OAuthV2, operação "VerifyAccessToken": verifica se o token de acesso do OAuth 2.0 é válido, corresponde o token ao aplicativo, verifica se o aplicativo é válido e, em seguida, corresponde o aplicativo a um produto de API. Consulte a página inicial do OAuth para mais informações.

Depois que as políticas e os produtos de API forem configurados, o processo a seguir será executado pela Apigee Borda:

Uma solicitação é recebida pelo Apigee Edge e encaminhada para o proxy de API apropriado.
Você executa uma política que verifica a chave de API ou o token de acesso OAuth apresentados pelo cliente.
O Edge resolve a chave de API ou o token de acesso para um perfil de aplicativo.
O Edge resolve a lista (se houver) de produtos de API associados ao aplicativo.
O primeiro produto de API que corresponde é usado para preencher variáveis de cota.
Se nenhum produto de API corresponder à chave de API ou ao token de acesso, a solicitação será rejeitada.
O Edge aplica o controle de acesso baseado em URI (ambiente, proxy de API e caminho de URI) de acordo com a Configurações do produto da API, junto com as configurações de cota.