Configurar notificações usando modelos de notificação

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

O que são modelos de notificação?

A monetização oferece um conjunto de modelos que definem textos de exemplo para vários tipos de notificações de evento. Você pode personalizar qualquer um desses modelos para:

  • Notificar todos os desenvolvedores sobre eventos como novos produtos, novas versões dos T&C ou novos planos de preços.
  • Notificar os desenvolvedores afetados sobre eventos, como um plano de tarifas revisado.
  • Notificar um provedor de API sobre eventos relacionados a desenvolvedores, como quando um desenvolvedor se registra para uma conta ou assina um plano de taxas.
  • Notificar todos os administradores da empresa sobre um evento específico.

Como alternativa, crie um webhook que defina um manipulador de callback HTTP e configure a condição que aciona o webhook, conforme descrito em Configurar notificações usando webhooks.

Como explorar a página "Notificações"

Acesse a página "Notificações", conforme descrito abaixo.

Edge

Para acessar a página "Notificações" usando a interface do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Publicar > Monetização > Notificações na barra de navegação à esquerda.

A página "Notificações" é exibida.

Conforme destacado na figura, na página "Notificações", é possível:

Edge clássico (nuvem privada)

Para acessar a página "Notificações" usando a interface clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.

  2. Selecione Administrador > Notificações na barra de navegação superior.

Na página "Notificações", é possível:

Como editar notificações

Para editar uma notificação usando a interface:

  1. Acesse a página "Notificações".
  2. Clique no ao lado da notificação que você quer editar para expandir os detalhes.
  3. Edite os campos "Assunto", "Corpo" e "Destinatário" (se disponível), conforme necessário.

    Para saber quais variáveis podem ser especificadas em um modelo de notificação, consulte Como usar variáveis em modelos de notificação.

    Consulte as seções a seguir para mais informações sobre como editar notificações em cada categoria:

  4. Ative uma notificação marcando a caixa de seleção ao lado dela.
  5. Repita as etapas de 2 a 4 para editar outras notificações.
  6. Clique em Salvar para salvar todas as mudanças.

Uma mensagem é exibida para confirmar que as notificações foram salvas. A operação de salvamento pode levar alguns minutos.

Como editar notificações para notificar todos os desenvolvedores

As notificações dos tipos de eventos selecionados na seção Notificar todos os desenvolvedores são enviadas a todos os desenvolvedores.

As notificações são programadas para serem executadas no final do dia. Depois que as notificações são enviadas, as caixas de seleção do evento são limpas automaticamente. É necessário selecioná-los novamente para programar notificações para os tipos de evento associados.

A tabela a seguir lista as notificações com base nos tipos de evento na seção "Notificar todos os desenvolvedores". Para mais informações, consulte Editar notificações usando a interface.

Tipo de evento Gatilho Observações
Novo pacote Um novo pacote de API está disponível

Adicione o nome de cada novo pacote (e dos produtos contidos em cada um deles) ao corpo do modelo de e-mail como parte da atualização. Você também pode adicionar um link para o portal do desenvolvedor ou qualquer outro site que ofereça mais informações sobre a notificação.
Novo produto Novo produto de API disponível

Adicione o nome de cada novo produto ao corpo do modelo de e-mail como parte da atualização. Também é possível adicionar um link para o portal do desenvolvedor ou qualquer outro site que ofereça mais informações sobre a notificação.
Novos mercados/cobertura Novos produtos de API estão disponíveis em mercados geográficos específicos

Adicione o nome de cada novo mercado e os produtos relevantes ao corpo do modelo de e-mail como parte da sua atualização. Você também pode adicionar um link para o portal do desenvolvedor ou qualquer outro site que ofereça mais informações sobre a notificação.

Editar notificações para notificar os desenvolvedores afetados

As notificações dos tipos de eventos selecionados na seção Notificar desenvolvedores afetados são enviadas apenas para os desenvolvedores afetados por esses tipos de eventos. Por exemplo, se você selecionar o evento "Plano de preços revisado", uma notificação será enviada apenas para os desenvolvedores que aceitaram o plano de preços.

A tabela a seguir lista as notificações com base nos tipos de evento da seção "Notificar os desenvolvedores afetados". Para mais informações, consulte Editar notificações usando a interface.

Tipo de evento Gatilho Observações
Termos e Condições não aceitos ou expirados Um novo conjunto de T&Cs foi publicado e o desenvolvedor ainda não os aceitou

A notificação é enviada 30 dias, 7 dias e 1 dia antes da entrada em vigor dos novos T&Cs.
Novo plano de tarifa Novos planos de tarifas são publicados

Se o plano de tarifas for:

  • No plano Standard, todos os desenvolvedores são notificados.
  • No plano de tarifas da categoria de desenvolvedor, somente os desenvolvedores dessa categoria vão ser notificados.
  • Plano de preços do desenvolvedor, apenas o desenvolvedor específico é notificado.
Plano de tarifa revisado Uma versão mais recente de um plano de tarifas comprado está disponível

Somente os desenvolvedores que compraram a versão atual vão ser notificados. A notificação permite que os desenvolvedores revisem a nova versão e encerrem ou mudem de planos se não quiserem aceitar as novas taxas.
Plano de tarifas expirado O plano de tarifação expirou e não tem um plano de acompanhamento

Essa notificação é enviada quando você define inicialmente a expiração do plano de preços, com notificações adicionais enviadas 30, 7 e 1 dia antes da data de validade. Apenas os desenvolvedores que compraram o plano de preços que será expirado vão receber uma notificação.
Plano de tarifa renovado A assinatura do plano de tarifa foi renovada.

Informe ao desenvolvedor que as taxas aplicáveis serão cobradas.
Limite de taxa excedido O limite do plano de taxa foi excedido

Informe ao desenvolvedor que as taxas aplicáveis serão cobradas.
Plano de tarifas Freemium esgotado Os períodos de uso sem custo financeiro, medidos pela contagem de transações ou por dias, se esgotaram

O período de uso sem custo financeiro é definido pelo seu plano de preço freemium.
Documento de faturamento publicado

Documentos de faturamento (como faturas) do desenvolvedor estão disponíveis.
O desenvolvedor se inscreve no novo plano de taxas O desenvolvedor se inscreve em um novo plano de taxas.

Como editar notificações para provedores de API Notify

As notificações para os tipos de eventos selecionados na seção Notificar provedor de API são enviadas ao provedor de API especificado.

A tabela a seguir lista as notificações com base nos tipos de evento na seção "Fornecedor da API Notify". Para mais informações, consulte Editar notificações usando a interface.

Tipo de evento Gatilho
Novo desenvolvedor se inscreve

O desenvolvedor se registrou para uma conta.
O desenvolvedor adiciona um app

O desenvolvedor criou um novo aplicativo.
Inscrição de desenvolvedor para o novo plano de preços

O desenvolvedor se inscreveu em um plano de taxa.
O desenvolvedor muda os detalhes financeiros

O desenvolvedor mudou os detalhes financeiros, como o nome ou o endereço da empresa.

Como ativar ou desativar uma notificação

Para ativar ou desativar uma notificação usando a interface:

  1. Acesse a página Notificações.
  2. Ative ou desative uma notificação selecionando ou desmarcando, respectivamente, a caixa de seleção ao lado dela.
  3. Clique em Salvar para salvar todas as mudanças.

O salvamento pode levar alguns minutos. Uma mensagem é exibida para confirmar que as notificações foram salvas.

Configurar notificações usando modelos com a API

Configure notificações usando a API, conforme descrito nas seções a seguir.

Como gerenciar modelos de notificação usando a API

Gerencie modelos de notificação usando a API, conforme descrito nas seções a seguir:

Visualizar todos os modelos de notificação usando a API

É possível listar todos os modelos de notificação fornecidos pela monetização emitindo uma solicitação GET para /mint/organizations/{org_name}/notification-email-templates. Exemplo:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/notification-email-templates" \
  -u email:password

Por exemplo, veja a seguir um modelo de evento que notifica os desenvolvedores sobre a disponibilidade de um novo produto de API:

{
    "createdDate" : 1376975394984,
    "htmlImage" : "<p>Dear ${developer.legalName} , ${developer.name} <br /> Introducing _________. For more details visit us at _________________</p>",
    "id" : "4d81ea64-d005-4010-b0a7-6ec8a5c3954b",
    "name" : "DEFAULT_NEW_PRODUCT_TEMPLATE",
    "orgId" : "myorg",
    "source" : "Mail Man Test",
    "subject" : "Notification of new product",
    "updatedDate" : 1376975394984
}

Como visualizar um modelo de notificação usando a API

Para visualizar um modelo de notificação, emita uma solicitação GET para /mint/organizations/{org_name}/notification-email-templates/{template_id}, em que {template_id} é o ID do modelo. Exemplo:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-email-templates/4d81ea64-d005-4010-b0a7-6ec8a5c3954b" \
  -H "Accept:application/json"  \
  -u email:password

Os itens nos modelos que começam com $ são variáveis. Para mais informações, consulte Como usar variáveis em modelos de notificação. Suponha que as variáveis na notificação sejam avaliadas para os seguintes valores:

  • ${developer.legalName}.XYZ company
  • ${developer.name}.DEV1
  • ${QUOTA_TYPE}.Transactions
  • ${PERCENT}.90%
  • ${QUOTA_UNIT}.Calls
  • ${QUOTA_LIMIT}.100
  • ${ratePlan.monetizationPackage.products.name}.X
  • ${EXPIRY_DATE}.2016-09-30

A mensagem de notificação fornecida pelo modelo seria:

    "Dear XYZ company, DEV1
    You have exceeded Transactions of 90% calls of 100 calls for X product. Your API calls will be blocked till 2016-09-30"

Como editar um modelo de notificação usando a API

Edite um modelo de notificação emitindo uma solicitação PUT para /nint/organizations/{org_name}/notification-email-templates/{template_id}. Forneça o conteúdo alterado do modelo no corpo da solicitação.

Ao personalizar a mensagem em um modelo de notificação, é possível incluir uma ou mais variáveis. Para mais informações, consulte Como usar variáveis em modelos de notificação.

Por exemplo, a solicitação a seguir edita o conteúdo de uma nova notificação de produto de API:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-email-templates/4d81ea64-d005-4010-b0a7-6ec8a5c3954b " \
  -H "Content-Type: application/json" \
  -d '{
    "id" : "4d81ea64-d005-4010-b0a7-6ec8a5c3954b",
    "htmlImage" : "<p>Exciting news, we have added a new product :${Product.name}. See details in <a href="${Product.url}">New Products</a> </p>",
    "name" : "NewProductNotification",
    "organization": {
    "id": "{org_name}"
    },
    "source" : "Mail Man Test ",
    "subject" : "New Product Available: ${Product.name}"
  }' \
  -u email:password

Como gerenciar condições e ações de notificação usando a API

Gerencie condições e ações de notificação usando a API, conforme descrito nas seções a seguir.

Como criar uma condição e uma ação de notificação usando a API

Crie uma condição e uma ação de notificação que resultem em uma notificação automática emitindo uma solicitação POST para /mint/organizations/{org_name}/notification-conditions.

Ao fazer a solicitação, especifique no corpo da solicitação a condição que resulta na notificação e as ações a serem realizadas quando a condição for atendida (como o envio de um e-mail de notificação).

Para definir os detalhes da condição de notificação, especifique um ou mais valores de atributo. Consulte Propriedades de configuração para condições de notificação e confira uma lista de atributos. Para uma notificação de evento, a condição pode ser acionada quando um novo produto é publicado.

Ao definir o actions, consulte o modelo de notificação aplicável. Consulte Propriedades de configuração para ações de notificação para conferir uma lista de ações.

Por exemplo, a solicitação a seguir especifica que, quando o atributo é NEW_PRODUCT e o valor do atributo PUBLISHED é true, envie a notificação no modelo com o ID 01191bf9-5fdd-45bf-8130-3f024694e63 (este é o DEFAULT_NEW_PRODUCT_TEMPLATE).

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions" \
  -H "Content-Type:application/json"
  -d '{
    "notificationCondition": [
    {
      "attribute": "NEW_PRODUCT"
    },
    {
      "attribute": "PUBLISHED",
      "value": "true"
    }
    ],
    "actions": [{
      "actionAttribute": "DEV_ID",
      "value": "ANY",
      "templateId": "01191bf9-5fdd-45bf-8130-3f024694e63"
    }]
  }' \
  -u email:password

Como conferir uma condição e uma ação de notificação usando a API

Veja uma condição e ação de notificação emitindo uma solicitação GET para organizations/{org_name}/notification-conditions/{condition_Id}, em que {condition_Id} é o ID da condição. O ID é retornado quando você cria a condição de notificação. Exemplo:

curl -X GET "https://api.enterprise.apigee.com /v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4" \
  -H "Accept:application/json" \
  -u email:password

Veja a seguir um exemplo de resposta:

    {
    "actions" : [ {
    "actionAttribute" : "DEV_ID",
    "id" : "141ba00c-d7bd-4fef-b339-9d58b83255f4",
    "templateId" : "766aba4f-0f7a-4555-b48e-d707c48b8f4c",
    "value" : "ANY"
    }, {
    "actionAttribute" : "ORG_EMAIL",
    "id" : "21486ce1-4290-4a55-b415-165af3e93c9d",
    "templateId" : "efa4ce63-7c08-4876-984b-6878ec435994",
    "value" : "DEFAULT_LIMIT_NOTIFICATION_EMAIL"
    } ],
    "notificationCondition" : [ {
    "attribute" : "Balance",
    "id" : "2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4",
    "organization" : {
    ...
    },
    "value" : "< 0"
    } ]
    }

Como editar uma condição e uma ação de notificação usando a API

Edite uma condição e uma ação de notificação emitindo uma solicitação POST para organizations/{org_name}/notification-conditions/{condition_Id}, em que {condition_Id} é o ID da condição. O ID é retornado quando você cria a condição de notificação. Ao emitir a solicitação, especifique no corpo da solicitação as mudanças que você quer fazer na ação ou condição de notificação.

Exemplo:

   $ curl -H "Content-Type:application/json" -X POST -d \
    ' {
    "notificationCondition": [
    {
      "attribute": "NEW_PRODUCT"
    },
    {
    "attribute": "PUBLISHED",
    "value": "true"
    }
    ],
    "actions": [{
      "actionAttribute": "DEV_ID",
      "value": "ANY",
      "templateId": "01191bf9-5fdd-45bf-8130-3f024694e63"
    }]
    }' \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4" \
  -u email:password

Como excluir uma condição e uma ação de notificação usando a API

Exclua uma condição de notificação emitindo uma solicitação DELETE para organizations/{org_name}notification-conditions/{condition_Id}. Exemplo:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4"  \
  -H "Accept:application/json"  \
  -u email:password

Propriedades de configuração das condições de notificação

As propriedades de configuração a seguir para condições de notificação estão disponíveis ao usar a API.

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

Detalhes da condição de notificação. Você pode especificar um ou mais atributos para refinar a condição de notificação.

O valor pode ser um ou mais destes:

  • ADD_RATEPLAN
  • ADHOC_NOTIFY_DEVELOPERS
  • BILLING_DOCS_PUBLISHED
  • COMPANY_ACCEPTS_INVITATION
  • COMPANY_CANCELS_INVITATION
  • COMPANY_DECLINES_INVITATION
  • COMPANY_INVITES_DEVELOPER
  • CREATE_APPLICATION
  • CREATE_DEVELOPER
  • DATE
  • DEVELOPER_ACCEPTS_INVITATION
  • DEVELOPER_CANCELS_INVITATION
  • DEVELOPER_DECLINES_INVITATION
  • DEVELOPER_INVITES_COMPANY
  • EXPIRING_TNC
  • FeeExposure
  • FREEMIUM_USED_UP
  • NEW_PACKAGE
  • NEW_PRODUCT
  • PUBLISHED
  • RATEPLAN
  • RATEPLAN_ACCEPTED
  • RATEPLAN_ENDED
  • RATEPLAN_EXPIRED
  • RATEPLAN_RENEWED
  • RATEPLAN_REVISION
  • Transactions
  • UPDATE_DEVELOPER
  • UsageTarget (válido apenas para configurar webhooks)
 N/A Sim
value

Valor do atributo.

 N/A Não
associatedCondition

Referência a uma condição associada.

 N/A Não

Propriedades de configuração para ações de notificação

As propriedades de configuração a seguir estão disponíveis para ações de notificação ao usar a API.

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

Método usado para identificar o destinatário da notificação. O valor pode ser um ou mais dos seguintes:

  • ORG_EMAIL. O destinatário da notificação é identificado pelo endereço de e-mail.
  • DEV_ID. O destinatário da notificação é identificado pelo ID do desenvolvedor (endereço de e-mail).
  • COMPANY_ADMINS. A notificação é enviada a todos os administradores da empresa, independentemente do valor definido. Observe que os administradores da empresa são diferentes dos administradores da organização.
  • WEBHOOK. As informações do destinatário da notificação são enviadas para o gerenciador de callback webhook. Consulte Configurar notificações usando webhooks.
 N/A Sim
value

Valor do atributo de ação.

Se actionAttribute for definido como ORG_EMAIL ou DEV_ID, um valor ANY enviará a notificação para qualquer destinatário aplicável, por exemplo, qualquer endereço ORG_EMAIL ou qualquer DEV_ID.

Se actionAttribute estiver definido como WEBHOOK, defina esse valor como o ID do webhook.

Se actionAttribute for definido como COMPANY_ADMINS, esse valor será ignorado. A notificação será enviada para todos os administradores da empresa.

 N/A Sim
templateID

ID do modelo de notificação.

Observação:essa opção não é válida se actionAttribute for definido como WEBHOOK.

 N/A Sim
postURL

Gerenciador de callback para o webhook.

Observação:essa opção é obrigatória se actionAttribute for definido como WEBHOOK. Essa opção não é válida se o valor for definido como ORG_EMAIL, DEV_ID ou COMPANY_ADMINS.

 N/A Sim

Como usar variáveis em modelos de notificação

Ao editar a mensagem em um modelo de notificação, é possível incluir uma ou mais variáveis, usando a linguagem de expressão Spring (SpEL), para representar os valores retornados no objeto de transação.

A tabela a seguir resume as variáveis de modelo de notificação mais usadas.

Variável Descrição
${application.name}

Nome de um aplicativo.
${application.products.name} Nome de um produto incluído em um aplicativo.
${BALANCE} Saldo de uma determinada cota.
${developer.legalName}

Nome da empresa de um desenvolvedor.
${developer.name}

Nome de um desenvolvedor.
${EXPIRY_DATE}

Data ou hora em que um limite expira ou é redefinido.
${LONG_PERCENT} Porcentagem de um limite atingido pelo uso atual, sem o símbolo de porcentagem. Por exemplo, 50
${PERCENT}

Porcentagem de um limite atingido pelo uso atual, com o símbolo de %. Por exemplo, 50%.
${products.displayName} Nome de exibição definido para um produto.
${QUOTA_TYPE}

Tipo de limite (volume de transações, limite de gastos ou exposição a taxas).
${QUOTA_UNIT}

Unidade básica de um limite: moeda (para um limite de gastos) ou chamadas (para um limite de transações).
${QUOTA_LIMIT}

Valor de um limite.
${ratePlan.displayName} Nome de exibição definido para um plano de taxa.
${ratePlan.endDate} Data em que um provedor de API encerrou um plano de tarifas.
${ratePlan.monetizationPackage.displayName}

Nome de um pacote de API.
${ratePlan.monetizationPackage.name} Nome de um pacote de monetização.
${ratePlan.monetizationPackage.products.displayName}

Nome de exibição definido para um produto de API.
${ratePlan.monetizationPackage.products.name} Nome de um produto incluído em um pacote de monetização.
${ratePlan.startDate} Data em que um plano de preços foi criado.
${USAGE} Uso atual (receita total ou cobranças ou volume).
${USER}

Nome de um usuário.

Personalizar o endereço de e-mail para resposta

Para monetização, um endereço noreply@apigee.com padrão é configurado para usar nas notificações por e-mail enviadas para empresas e desenvolvedores. Entre em contato com o suporte da Apigee para configurar um nome e endereço de resposta personalizados para sua organização.