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 sua receita de produtos do AWS Marketplace para oportunidades específicas do AWS Marketplace Offers Partner Central. and/or AWS 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?

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

  • A atribuição é um recurso nomeado pelo parceiro 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 Sandbox para teste) e 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 tarefa de alocação.

Um ID de atribuição de receita pode ser usado 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 ofertas and/or ACE de ofertas do Marketplace aplicáveis e AWS mapeie sua receita de produtos já medida a essas ofertas específicas. Nenhuma alteração nas tags de recursos ou nas cadeias de caracteres do agente do usuário existentes é necessária.

  • 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 Revenue Attribution Service. 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 uma ID de atribuição de receita usando a ação da CreateRevenueAttribution API. O retornado Id e 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 teste.

  • 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.

Opcionalmente, os parceiros podem fornecer:

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

  • MarketplaceProduct— o produto do AWS Marketplace a ser associado a essa atribuição. Forneça ProductIdentifier (o ID do produto do 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 comprado pelo cliente. Isso é ú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.

Melhor prática: 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 por meio da Conexão de Conta de Parceiro (PAC) e mostra o resolvido ProductCode e ProductType (por exemplo,, SaaSAMI,ML) na resposta. Se o produto não for de propriedade de uma conta autorizada, a API retornará ValidationException com o motivoPRODUCT_NOT_FOUND_OR_NOT_OWNED.

A resposta retorna o novo Id (formatora-[a-z0-9]{13})Arn, MarketplaceProduct os atributos 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ó precisarão fornecer o ID da oferta; atribuem 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 de uma determinada ID de atribuição de receita e do 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 TaskId com statusIN_PROGRESS. A validação comercial (verificações de limite, regras de imutabilidade, pesquisas de dependências em relação ao Marketplace e ao ACE) é executada de forma assíncrona e os resultados por registro são descobertos por meio de. GetRevenueAttributionAllocationsTask

Para monitorar uma tarefa enviada, os parceiros fazem uma pesquisa GetRevenueAttributionAllocationsTask com o ID de recurso de atribuição de receita ou ARN. A resposta avança 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 se o registro falhar.

Os parceiros devem recuperar os resultados das tarefas 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 7º dia do mês atual, a atribuição do mês de cobrança anterior não poderá mais ser modificada. As atualizações em uma entrada do mês atual ou do 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 UPDATE para cada entrada afetada. O padrão de tarefa assíncrona lida com atualizações e criações de maneira uniforme.

Atualização de 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 tag-on-create não podem ser alterados após a criação. Para remarcar 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.

Opcionalmente, os parceiros podem 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 envio 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 do recurso:

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

  • O Catalog 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 MarketplaceProduct foram definidos na criação):

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

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

  • ProductType—SaaS,AMI, ContainerML,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 a devolução do mais recente.

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

Listando IDs de atribuição de receita

Os parceiros podem ver todas as IDs de atribuição de receita em suas contas usando a ação de 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 para 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 páginas adicionais estiverem disponíveis.

Listando entradas mensais de alocação de custos

Os parceiros podem listar as entradas mensais de alocação de custos para uma ID de atribuição de receita específica 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— liste somente as entradas associadas a uma oportunidade específica do Partner Central.

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

A resposta inclui informações resumidas para cada entrada: aAllocationId, a ID da oferta ou ID da oportunidade associada, 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:

  • Todas as IDs de atribuição de receita criadas nos últimos 30 dias, classificadas 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