Como gerenciar pacotes de produtos da API

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Agrupe um ou mais produtos de API em um único contêiner monetizado, chamado de pacote de produtos de API, conforme descrito nas seções a seguir.

O que é um pacote de produtos da API?

Um pacote de produtos de API é um conjunto de produtos de API apresentado aos desenvolvedores como um grupo e geralmente associado a um ou mais planos de tarifas para monetização. É possível criar vários pacotes de produtos de API e incluir um ou mais produtos de API em cada um. É possível colocar os mesmos produtos de API em pacotes diferentes e associá-los a planos de tarifas iguais ou diferentes.

Os desenvolvedores podem registrar seus aplicativos para usar um pacote de produtos da API somente comprando um dos planos de tarifas em vigor. Um pacote de produtos da API não fica visível para os desenvolvedores até que você adicione e publique (como público) um plano de tarifas para ele (com uma data de início na data atual ou em uma data futura), conforme descrito em Como gerenciar planos de tarifas. Depois que você adicionar e publicar um plano de tarifas, os desenvolvedores que fizerem login no portal do desenvolvedor poderão selecionar o pacote de produtos da API e escolher o plano. Como alternativa, você pode aceitar um plano de tarifa para um desenvolvedor usando a API Management. Para mais informações, consulte Comprar planos de tarifas publicados usando a API.

Depois de adicionar um produto de API a um pacote de produtos de API, pode ser necessário configurar faixas de preços para o produto da API. Você só precisará fazer isso se todas as condições a seguir forem verdadeiras:

  • Você configurou um plano de tarifas de participação na receita para o produto de API.
  • Os desenvolvedores cobram de terceiros pelo uso de recursos no produto de API.
  • Há uma restrição mínima ou máxima no valor que os desenvolvedores podem cobrar, e você quer notificá-los sobre a restrição.

Os preços mínimo e máximo são exibidos nos detalhes do pacote de produtos da API.

Como explorar a página "Pacotes de produtos"

Acesse a página "Pacotes de produtos", conforme descrito abaixo.

Edge

Para acessar a página de pacotes de produtos da API usando a interface do Edge, selecione Publicar > Monetização > Pacotes de produtos na barra de navegação à esquerda.

Conforme destacado na figura anterior, a página "Pacotes de produtos" permite que você:

Você pode gerenciar os produtos de API em um pacote de produtos ou excluir um pacote de produtos (se nenhum plano de tarifas estiver definido) usando somente a API.

Borda clássica (nuvem privada)

Para acessar a página de pacotes de API usando a interface clássica do Edge, selecione Publish > Packages na barra de navegação superior.

Na página "Pacotes de API", você pode:

  • Conferir informações resumidas de todos os pacotes de API, incluindo os produtos de API que eles contêm e os planos de tarifas associados
  • Adicionar um pacote de API
  • Editar um pacote de API
  • Adicionar e gerenciar planos de tarifas
  • Alternar a configuração de acesso do plano de tarifa (público/privado)
  • Filtrar a lista de pacotes

É possível gerenciar os produtos de API em um pacote de API ou excluir um pacote de API (se não houver planos de tarifas definidos) usando somente a API.

Como adicionar um pacote de produtos

Para adicionar um pacote de produtos da API, faça o seguinte:

  1. Clique em + API Product Bundle na página de pacotes de produto.
  2. Insira um nome para o pacote de produtos da API.
  3. Digite o nome de um produto de API no campo Adicionar um produto.

    Conforme você digita o nome de um produto de API, uma lista de produtos de API que contêm a string é exibida em um menu suspenso. Clique no nome de um produto de API para adicionar ao pacote. Repita para adicionar outros produtos de API.

  4. Repita a etapa 3 para adicionar outros nomes de produtos da API.
  5. Para cada produto de API adicionado, configure a política de registro de transações.
  6. Clique em Salvar pacote de produtos.

Editando um pacote de produtos

Para editar um pacote de produtos:

  1. Na página "Pacotes de produtos", clique na linha do pacote que você quer editar.

    O painel do pacote de produtos é exibido.

  2. Edite os campos do pacote de produtos conforme necessário.

    Consulte Configurar a política de gravação de transações para mais informações.

  3. Clique em Atualizar pacote de produto.

Como gerenciar pacotes de produtos de API usando a API

As seções a seguir descrevem como gerenciar pacotes de produtos de API usando a API.

Como criar um pacote de produtos de API usando a API

Para criar um pacote de produtos da API, emita uma solicitação POST para /organizations/{org_name}/monetization-packages. Ao emitir a solicitação, é preciso:

  • Identificar os produtos de API que vão ser incluídos no pacote.
  • Especifique um nome e uma descrição para o pacote de produtos da API.
  • Defina um indicador de status para o pacote de produtos da API. Esse indicador pode ter um dos seguintes valores: CREATED, ACTIVE, INACTIVE. No momento, o valor do indicador de status especificado é mantido no pacote de produtos da API, mas não é usado para nenhuma finalidade.

Também é possível especificar a organização.

Consulte as propriedades de configuração do pacote de produtos de API para uma lista de opções expostas à API.

Exemplo:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "description": "payment messaging package",
     "displayName": "Payment Messaging Package",
     "name": "Payment Messaging Package",
     "organization": { "id": "{org_name}" },
     "product": [
       { "id": "messaging" },
       { "id": "payment" }
     ],
     "status": "CREATED"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages" \
-u email:password

Veja a seguir um exemplo de resposta:

{
   "description" : "payment messaging package",
   "displayName" : "Payment Messaging Package",
   "id" : "payment_messaging_package",
   "name" : "Payment Messaging Package",
   "organization" : {
     "id" : "{org_name}",
     "separateInvoiceForFees" : false
   },
   "product" : [ {
     "customAtt1Name" : "user",
     "description" : "Messaging",
     "displayName" : "Messaging",
     "id" : "messaging",
     "name" : "messaging",
     "organization" : {
       "id" : "{org_name}",
       "separateInvoiceForFees" : false
     },
     "status" : "CREATED"
   }, {
     "customAtt1Name" : "user",
     "description" : "Payment",
     "displayName" : "Payment",
     "id" : "payment",
     "name" : "payment",
     "organization" : {
       "id" : "{org_name}",
       "separateInvoiceForFees" : false
     },
     "status" : "CREATED"
   }],
   "status" : "CREATED"
 }

A resposta inclui mais informações sobre os produtos de API e todos os atributos personalizados especificados para esses produtos. Os atributos personalizados são especificados quando você cria um produto de API. Os atributos personalizados de um produto de API podem ser incluídos em vários planos de preços. Por exemplo, se você configurar um plano de tabela de preços em que o desenvolvedor cobra cada transação, será possível definir a taxa para o plano com base em um atributo personalizado, como o número de bytes transmitidos em uma transação.

Como gerenciar os produtos de API em um pacote de produtos usando a API

É possível adicionar ou excluir um produto de API de um pacote de produtos de API usando a API, conforme descrito nas seções a seguir.

Adicionar um produto de API a um pacote de produtos de API

Para adicionar um produto da API a um pacote de produtos da API, emita uma solicitação POST para organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}, em que {org_name} especifica o nome da organização, {package_id} especifica o nome do pacote de produtos da API e {product_id} especifica o ID do produto da API.

Exemplo:

$ curl -H "Accept:application/json" -X POST -d \
'{}'\
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \
-u email:password

Adicionar um produto de API a um pacote de produtos com planos de preços específicos para produtos de API

Para adicionar um produto de API a um pacote de produtos que tenha um ou mais planos de preços específicos do produto de API definidos (tabela de preços ou participação na receita), envie uma solicitação POST para organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}, em que {org_name} especifica o nome da organização, {package_id} especifica o nome do pacote de produtos da API e {product_id} especifica o ID dele.

É preciso transmitir os detalhes do plano de tarifa para o novo produto de API no corpo da solicitação. Com exceção da matriz ratePlanRates, os valores do plano de tarifas precisam corresponder aos especificados para todos os outros produtos da API. Para mais informações sobre os atributos de plano de tarifas que podem ser definidos, consulte Propriedades de configuração de planos de tarifas.

Exemplo:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "ratePlan": [ 
        {
            "id": "mypackage_rateplan1",
            "ratePlanDetails": [
                {
                    "currency": {
                        "id": "usd"
                    },
                    "duration": 1,
                    "durationType": "MONTH",
                    "meteringType": "UNIT",
                    "organization" : {
                        "id": "{org_name}",
                    "paymentDueDays": "30",
                    "ratePlanRates": [
                        {
                            "rate": "1.99",
                            "startUnit": "0",
                            "type": "RATECARD"
                        }
                    ],
                    "ratingParameter": "VOLUME",
                    "type": "RATECARD"
                }
            ]
        }
    ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \
-u email:password

Excluir um produto de API de um pacote de produtos de API

Para excluir um produto da API de um pacote, envie uma solicitação DELETE para organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}, em que {org_name} especifica o nome da organização, {package_id} especifica o nome do pacote de produtos da API e {product_id} especifica o ID do produto da API.

Exemplo:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \
-u email:password

Como visualizar pacotes de produtos de API usando a API

É possível recuperar um pacote de produtos de API específico ou todos os pacotes de produtos de API em uma organização. Também é possível recuperar pacotes de produtos de API que tenham transações em um determinado período, ou seja, apenas pacotes para os quais os usuários invocam apps que acessam APIs nesses pacotes em datas de início e término específicas.

Visualização de um pacote de produtos de API específico:para recuperar um pacote específico de produtos da API, emita uma solicitação GET para /organizations/{org_name}/monetization-packages/{package_id}, em que {package_id} é a identificação do pacote de produtos da API. O ID é retornado na resposta quando você cria o pacote de produtos da API. Exemplo:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/payment_messaging_package" \
-u email:password

Visualização de todos os pacotes de produtos de API:para recuperar todos os pacotes de produtos de API de uma organização, emita uma solicitação GET para /organizations/{org_name}/monetization-packages. Exemplo:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages" \
-u email:password

É possível passar os seguintes parâmetros de consulta para filtrar os resultados:

Parâmetro de consulta Descrição
all Sinalização que especifica se todos os pacotes de produtos da API precisam ser devolvidos. Se definido como false, o número de pacotes de produtos da API retornados por página será definido pelo parâmetro de consulta size. O padrão é false.
size Número de pacotes de produtos da API retornados por página. O padrão é 20. Se o parâmetro de consulta all for definido como true, ele será ignorado.
page Número da página que você quer retornar (se o conteúdo for paginado). Se o parâmetro de consulta all estiver definido como true, ele será ignorado.

A resposta para a visualização de todos os pacotes de produtos de API em uma organização deve ser parecida com esta (somente parte da resposta é exibida):

{
  "monetizationPackage" : [ {
    "description" : "payment messaging package",
    "displayName" : "Payment Messaging Package",
    "id" : "payment_messaging_package",
    "name" : "Payment Messaging Package",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "description" : "Messaging",
      "displayName" : "Messaging",
      "id" : "messaging",
      "name" : "messaging",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    }, {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    } ],
    "status" : "CREATED"
  }, {
    "description" : "Communications",
    "displayName" : "Communications",
    "id" : "communications",
    "name" : "Communications",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "description" : "Location",
      "displayName" : "Location",
      "id" : "location",
      "name" : "location",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    }, {
      "customAtt1Name" : "user",
      "description" : "Messaging",
      "displayName" : "Messaging",
      "id" : "messaging",
      "name" : "messaging",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    } ],
    "status" : "CREATED"
  }, {
    "description" : "Payment",
    "displayName" : "Payment",
    "id" : "payment",
    "name" : "Payment",
    "organization" : {
     ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    } ],
    "status" : "CREATED"
  } ],
  "totalRecords" : 3
}

Visualização de pacotes de produtos da API com transações:para recuperar pacotes de produtos da API com transações em um determinado período, emita uma solicitação GET para /organizations/{org_name}/packages-with-transactions. Ao emitir a solicitação, você precisa especificar como parâmetros de consulta uma data de início e uma data de término para o período. Por exemplo, a solicitação a seguir recupera pacotes de produtos da API com transações durante o mês de agosto de 2013.

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/packages-with-transactions?START_DATE=2013-08-01&END_DATE=2013-08-31" \
-u email:password

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

{
  "monetizationPackage" : [ {
    "description" : "Payment Package",
    "displayName" : "Payment Package",
    "id" : "payment_package",
    "name" : "Payment Package",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "customAtt2Name" : "response size",
      "customAtt3Name" : "content-length",
      "description" : "payment api product",
      "displayName" : "payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "status == 'SUCCESS'"
    } ],
    "status" : "CREATED"
  }, {
    "description" : "messaging package",
    "displayName" : "Messaging Package",
    "id" : "messaging_package",
    "name" : "Messaging Package",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "customAtt2Name" : "response size",
      "customAtt3Name" : "content-length",
      "description" : "messaging api product",
      "displayName" : "messaging",
      "id" : "messaging",
      "name" : "messaging",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "status == 'SUCCESS'"
    } ],
    "status" : "CREATED"
  },
     ...
  } ]
}

Como visualizar pacotes de produtos de API aceitos por um desenvolvedor ou empresa usando a API

Para conferir os pacotes de produtos da API aceitos por um desenvolvedor ou empresa específica, emita uma solicitação GET para as seguintes APIs, respectivamente:

  • /organizations/{org_name}/developers/{developer_id}/monetization-packages, em que {developer_id} é o ID (endereço de e-mail) do desenvolvedor.
  • /organizations/{org_name}/companies/{company_id}/monetization-packages, em que {company_id} é o ID da empresa.

Ao emitir a solicitação, é possível especificar os seguintes parâmetros de consulta:

Parâmetro de consulta Descrição Padrão
current Sinalização que especifica se é preciso recuperar apenas pacotes de produtos de API ativos (current=true) ou todos os pacotes (current=false). Todos os planos de preços em um pacote ativo são considerados disponíveis. current=false
allAvailable Sinalização que especifica se todos os pacotes de produtos de API disponíveis (allAvailable=true) ou apenas pacotes de produtos de API disponíveis especificamente para o desenvolvedor ou a empresa (allAvailable=false). Todos estão disponíveis para os pacotes de produtos de API disponíveis para o desenvolvedor ou empresa especificado, além de outros desenvolvedores ou empresas. Os pacotes de produtos da API disponíveis especificamente para uma empresa ou um desenvolvedor contêm apenas planos de preços disponíveis exclusivamente para essa empresa ou desenvolvedor. allAvailable=true

Por exemplo, a solicitação a seguir recupera todos os pacotes de produtos de API aceitos por um desenvolvedor específico:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev1@myorg.com/monetization-packages" \
-u email:password

A solicitação a seguir recupera apenas pacotes de API ativos aceitos por uma empresa específica:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/myCompany/monetization-packages?current=true" \
-u email:password

Excluir um pacote de produtos de API usando a API

Você só poderá excluir um pacote de produtos de API se ele não tiver planos de preços definidos.

Para excluir um pacote de produtos da API sem planos de preços definidos, emita uma solicitação DELETE para organizations/{org_name}/monetization-packages/{package_id}, em que {org_name} especifica o nome da organização e {package_id} especifica o nome do pacote de produtos da API.

Exemplo:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}" \
-u email:password

Propriedades de configuração do pacote de produtos da API para a API

As seguintes opções de configuração de pacote de produtos da API são expostas à API:

Nome Descrição Padrão Obrigatório?
description

Uma descrição do pacote de produtos da API.

N/A Sim
displayName

O nome a ser exibido para o pacote de produtos da API (por exemplo, em um catálogo de pacotes de API).

N/A Sim
name

O nome do pacote de produtos da API.

N/A Sim
organization

A organização que contém o pacote de produtos da API.

N/A Não
product

Uma matriz de um ou mais produtos no pacote de produtos da API.

N/A Não
status

Um indicador de status para o pacote de produtos da API. Esse indicador pode ter um dos seguintes valores: CREATED, ACTIVE, INACTIVE.

N/A Sim