View a markdown version of this page

Trabalhando com seus IDs de atribuição de receita - AWS Central de Parceiros
O que é um ID de atribuição de receita?Trabalhando com seus IDs de atribuição de receita

A referência Central de Parceiros da AWS da API foi reestruturada. Para obter mais informações sobre as operações de API suportadas, consulte a Referência Central de Parceiros da AWS da API.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Trabalhando com seus IDs de atribuição de receita

Um ID de atribuição de receita é um identificador em nível de negócio que mapeia a receita de seus produtos do AWS Marketplace para oportunidades específicas do Marketplace and/or AWS Offers AWS Partner Central. Ele se baseia na implementação do Partner Revenue Measurement (PRM) em nível de produto: o PRM captura a receita total atribuída a um produto do Marketplace e um ID de atribuição de receita mapeia essa receita para negócios específicos de acordo com as porcentagens mensais de alocação de custos que você especificar.

O Revenue Attribution Service expõe APIs para criar, recuperar, listar e atualizar IDs de atribuição de receita e gerenciar suas entradas mensais de alocação de custos de forma assíncrona.

O que é um ID de atribuição de receita?

Um ID de atribuição de receita tem duas camadas:

  • A atribuição a um recurso chamado e descrito pelo parceiro identificado por um ID de ra- prefixo (por exemplo,) e um ARN. ra-aabbccddee001 Cada atribuição tem como escopo uma Catalog (para produção, AWS para testes) e Sandbox para a conta do parceiro.

  • Uma ou mais entradas mensais de alocação de custos. Cada entrada mapeia uma única combinação (ID da oferta ou ID da oportunidade, mês de cobrança) para uma porcentagem de alocação de custos. As entradas são gerenciadas em lotes de forma assíncrona por meio de um padrão de tarefas de alocação.

Uma ID de atribuição de receita pode ser usada de duas maneiras:

  • Como uma sobreposição em nível de negócio em sua implementação existente de PRM em nível de produto. Crie um ID de atribuição de receita, associe suas oportunidades de and/or ACE de ofertas do Marketplace aplicáveis e AWS mapeie sua receita de produto já mensurada a esses negócios específicos. Não é necessário alterar suas tags de recursos ou sequências de agentes de usuário existentes.

  • Como um identificador independente usado diretamente como um valor de tag de recurso (aws-apn-id=<RA ID>) ou em uma string de agente de usuário (APN_1.1/pc_<RA ID>$) para atribuir o AWS consumo a um negócio específico desde o início.

Trabalhando com seus IDs de atribuição de receita

Os parceiros podem gerenciar IDs de atribuição de receita e suas entradas mensais de alocação de custos por meio do Serviço de atribuição de receita. O ciclo de vida progride por meio de dois fluxos independentes: o fluxo de registro de atribuição (criar, atualizar, recuperar, listar) e o fluxo de alocações (iniciar uma tarefa em lote, pesquisar resultados, recuperar entradas individuais, listar entradas para uma atribuição).

Criação de um ID de atribuição de receita

A primeira etapa é criar um ID de atribuição de receita usando a ação da CreateRevenueAttribution API. O Id e retornado Arn pode ser usado imediatamente como um valor de tag de recurso ou em uma string de agente de usuário para atribuir o consumo. AWS

Ao criar um ID de atribuição de receita, os parceiros devem fornecer:

  • Catalog— AWS para produção ou Sandbox para testes.

  • Name— um nome legível por humanos para a atribuição. Deve ser exclusivo no Catálogo e na conta do parceiro. Máximo de 128 caracteres.

Os parceiros podem, opcionalmente, fornecer:

  • Description— descrição em texto livre da atribuição. Máximo de 1024 caracteres.

  • MarketplaceProduct— o produto AWS Marketplace a ser associado a essa atribuição. Forneça ProductIdentifier (o ID do produto Marketplace de 25 caracteres) e TenancyModel (MULTI_TENANTouSINGLE_TENANT). Se omitida na criação, a atribuição se aplica a todo o consumo medido pelo ID de atribuição de receita, independentemente do produto do Marketplace que o cliente comprou — útil quando uma única implantação abrange mais de uma listagem do Marketplace.

  • Tags— até 200 pares de valores-chave para organização de recursos. As chaves de tag devem ser exclusivas na solicitação.

Prática recomendada: forneça MarketplaceProduct.ProductIdentifier sempre que seu negócio estiver ancorado em uma listagem específica do Marketplace. Isso permite AWS validar se o produto é de propriedade da conta do parceiro chamador ou de uma conta subsidiária conectada via Partner Account Connection (PAC) e mostra o resolvido ProductCode e ProductType (por exemplo,, SaaSAMI,ML) na resposta. Se o produto não pertencer a uma conta autorizada, a API retornará ValidationException com razãoPRODUCT_NOT_FOUND_OR_NOT_OWNED.

A resposta retorna os MarketplaceProduct atributos novos Id (formatora-[a-z0-9]{13})Arn, resolvidos e o Version número inicial (que começa em 1 e aumenta em cada atualização subsequente).

Adicionar entradas mensais de alocação de custos

Depois que um ID de atribuição de receita é criado, os parceiros associam o AWS Marketplace Offers and/or ACE Opportunities a ele enviando um lote de entradas mensais de alocação de custos por meio da ação da API. StartRevenueAttributionAllocationsTask Essa é uma operação assíncrona que aceita até 250 alterações de alocação () CREATE and/or UPDATE por tarefa.

Cada entrada de alocação especifica:

  • ID da oferta ou ID da oportunidade — o identificador exclusivo do negócio que está sendo associado. Se uma oferta do Marketplace já estiver vinculada a uma oportunidade ACE, os parceiros só precisam fornecer o ID da oferta; atribui AWS automaticamente a receita à oportunidade vinculada.

  • Mês de cobrança — o mês civil ao qual a alocação de custos se aplica (por exemplo,2026-04).

  • % de alocação de custos — a parte do AWS consumo total do produto atribuível a essa oferta neste mês de cobrança. Necessário para produtos SaaS multilocatários, incluindo componentes hospedados por parceiros para implantações híbridas, nas quais os clientes compartilham a infraestrutura.

  • ID AWS da conta do cliente — a AWS conta do cliente que consome o produto. Necessário para produtos SaaS multilocatários.

A porcentagem total de alocação de custos em todas as entradas de alocação para uma determinada ID de atribuição de receita e para o mesmo mês de cobrança não deve exceder 100%. Se o total exceder 100%, a entrada ofensiva será rejeitada durante a validação comercial assíncrona com um código de erro por registro.

Validação síncrona: StartRevenueAttributionAllocationsTask executa a validação básica da forma de forma síncrona (tipos de campo, padrões, tamanho do lote). Se a validação básica for aprovada, a API retornará um status TaskId withIN_PROGRESS. A validação de negócios (verificações de limite, regras de imutabilidade, pesquisas de dependência em relação ao Marketplace e ao ACE) é executada de forma assíncrona e os resultados por registro são descobertos por meio dela. GetRevenueAttributionAllocationsTask

Para monitorar uma tarefa enviada, os parceiros pesquisam GetRevenueAttributionAllocationsTask com o ID do recurso de atribuição de receita ou ARN. A resposta progride de IN_PROGRESS para COMPLETED (independentemente de os registros individuais terem sido bem-sucedidos ou falhados) e retorna:

  • TaskStatus—IN_PROGRESS,COMPLETED, ou FAILED (falha na tarefa de nível superior).

  • RecordResults— para cada registro de entrada: o atribuído AllocationId (se bem-sucedido), o status por registro (SUCCEEDEDouFAILED) e um código de erro estruturado e uma mensagem em caso de falha no registro.

Os parceiros devem recuperar os resultados da tarefa imediatamente. Após a conclusão da tarefa, os resultados por registro podem ser reconciliados e qualquer entrada com falha pode ser corrigida e reenviada em uma nova tarefa.

Editando entradas mensais de alocação de custos

As entradas de alocação de custos são gerenciadas por mês de cobrança com estas regras:

  • Os parceiros podem adicionar uma nova entrada mensal para o mês de cobrança atual ou futuro a qualquer momento.

  • Os parceiros podem atualizar uma entrada mensal para o mês de cobrança atual ou futuro a qualquer momento.

  • Os parceiros podem atualizar a entrada do mês passado até o dia 7 do mês atual. Essa janela permite que os parceiros analisem o uso real no AWS Cost Explorer antes de finalizar a alocação do mês anterior.

Após o dia 7 do mês atual, a atribuição do mês de cobrança anterior não poderá mais ser modificada. As atualizações de uma entrada do mês atual ou futuro se aplicam a partir do próximo ciclo de cobrança mensal. A atribuição histórica dos meses anteriores não é recalculada retroativamente.

As atualizações nas entradas de alocação são enviadas por meio da mesma ação de StartRevenueAttributionAllocationsTask API Operation definida como UPDATE para cada entrada afetada. O padrão de tarefas assíncronas lida com atualizações e criações de maneira uniforme.

Atualizando um ID de atribuição de receita

Os parceiros podem atualizar o ID Description de atribuição de receita existente usando a ação da UpdateRevenueAttribution API. Caso contrário, o registro de atribuição em si é imutável —Name,MarketplaceProduct, e os valores de marcação na criação não podem ser alterados após a criação. Para marcar novamente o recurso, use as operações de AWS marcação padrão no ARN da atribuição.

Ao atualizar um ID de atribuição de receita, os parceiros devem fornecer:

  • Catalog— AWS ouSandbox.

  • Identifier— o ra- ID da atribuição a ser atualizada.

  • Version— a versão atual da atribuição para bloqueio otimista.

Os parceiros podem, opcionalmente, fornecer:

  • Description— a descrição atualizada em texto livre. Máximo de 1024 caracteres.

  • ClientToken— um token de idempotência para a atualização.

Bloqueio otimista: o Version campo garante que as atualizações sejam aplicadas somente se a atribuição não tiver sido alterada desde a última vez que foi recuperada. Se o enviado Version não corresponder à versão atual do recurso, a atualização será rejeitada com ConflictException uma mensagem incluindo os números da versão enviada e atual. A melhor prática é recuperar a versão mais recente GetRevenueAttribution antes de cada atualização.

Visualizando detalhes do ID de atribuição de receita

Os parceiros podem recuperar informações completas para um único ID de atribuição de receita usando a ação da GetRevenueAttribution API. Isso retorna:

Metadados de recursos:

  • Identificador exclusivo (Id) e nome de recurso da Amazon (Arn).

  • CatalogAquele em que a atribuição existe.

  • Name e Description.

  • O recuperado Version e o LatestVersion (use o mais recente para atualizações subsequentes).

Atributos do produto do Marketplace (se tiverem MarketplaceProduct sido definidos na criação):

  • ProductId— o ID do produto Marketplace fornecido pelo parceiro.

  • ProductCode— o código do produto AWS Marketplace resolvido a partir deProductId.

  • ProductType—SaaS,AMI,Container,ML,Data, ouProfessional Services.

  • TenancyModel— MULTI_TENANT ouSINGLE_TENANT.

Informações de auditoria:

  • CreatedDate e LastModifiedDate.

Opcionalmente, os parceiros podem fornecer uma Version informação específica na solicitação para recuperar uma versão histórica da atribuição. Omita Version para retornar o mais recente.

Para recuperar uma entrada específica de alocação de custos mensais, os parceiros usam a ação da GetRevenueAttributionAllocation API com a entrada. AllocationId Isso retorna a ID da oferta ou ID da oportunidade, o mês de cobrança, a porcentagem de alocação de custos, a ID da AWS conta do cliente e as informações de status e auditoria da entrada.

Listando IDs de atribuição de receita

Os parceiros podem ver todos os IDs de atribuição de receita em suas contas usando a ação da ListRevenueAttributions API. Isso retorna uma lista paginada de resumos de atribuição com recursos de filtragem e classificação.

Os parceiros podem filtrar os resultados por:

  • Catalog— AWS ou Sandbox (obrigatório).

  • Identifiers— uma lista de até 100 ra- IDs específicos para recuperar.

  • CreatedAfter/CreatedBefore— filtrar por intervalo de data e hora de criação (inclusive).

Os parceiros podem configurar a classificação dos resultados usando o Sort parâmetro:

  • SortBy— CreatedDate ouLastModifiedDate.

  • SortOrder— ASCENDING ouDESCENDING.

A resposta inclui um resumo de cada atribuição:Arn,,,Id, MarketplaceProduct atributos resolvidos CatalogName,, CreatedDateLastModifiedDate, os mais recentes Version e TotalRevenueAttributionAssociationCount (o número de entradas ativas de alocação de custos mensais vinculadas à atribuição).

Use MaxResults (padrão 25, máximo 100) e NextToken para paginar por meio de grandes conjuntos de resultados. A resposta inclui NextToken se houver páginas adicionais disponíveis.

Listando entradas mensais de alocação de custos

Os parceiros podem listar as entradas mensais de alocação de custos para um ID de atribuição de receita específico usando a ação da ListRevenueAttributionAllocations API. Isso retorna uma lista paginada de resumos de alocação com recursos de filtragem.

Os parceiros podem filtrar os resultados por:

  • MarketplaceOfferId— listar somente as entradas associadas a uma oferta específica do Marketplace.

  • AwsPartnerCentralOpportunityId— listar somente as entradas associadas a uma oportunidade específica do Partner Central.

  • BillingMonth— listar somente entradas para um mês civil específico.

A resposta inclui informações resumidas de cada entrada: a ID da oferta ou ID da oportunidade associadaAllocationId, a ID da AWS conta do cliente, o mês de cobrança, a porcentagem de alocação de custos, o nome e o status da entrada e os registros de data e hora da auditoria.

Criação de painéis: a combinação de ListRevenueAttributions e foi ListRevenueAttributionAllocations projetada para apoiar a criação de painéis de parceiros. Os parceiros podem criar visualizações como:

  • Todos os IDs de atribuição de receita criados nos últimos 30 dias, classificados por data de criação.

  • Todas as entradas mensais de alocação de custos para uma oferta específica do Marketplace em vários IDs de atribuição de receita.

  • Todas as entradas de alocação de custos para o mês de cobrança atual, para validar que os totais não excedam 100% por atribuição.

  • Todos os IDs de atribuição de receita que tenham pelo menos uma entrada de alocação ativa (). TotalRevenueAttributionAssociationCount > 0