Comprar um complemento para uma assinaturaPurchase an add-on to a subscription

Aplica-se aApplies To

  • Partner CenterPartner Center
  • Partner Center operado pela 21VianetPartner Center operated by 21Vianet
  • Partner Center do Microsoft Cloud for US GovernmentPartner Center for Microsoft Cloud for US Government

Como comprar um complemento em uma assinatura existente.How to purchase an add-on to an existing subscription.

Pré-requisitosPrerequisites

  • Credenciais, conforme descrito em Autenticação do Partner Center.Credentials as described in Partner Center authentication. Esse cenário dá suporte à autenticação com aplicativos autônomos e aplicativos + credenciais de usuário.This scenario supports authentication with both standalone App and App+User credentials.

  • Uma ID do cliente (customer-tenant-id).A customer ID (customer-tenant-id). Se você não souber a ID do cliente, poderá procurar no painel do Partner Center.If you don't know the customer's ID, you can look it up in the Partner Center dashboard. Selecione CSP no menu do Partner Center e, em seguida, Clientes.Select CSP from the Partner Center menu, followed by Customers. Selecione o cliente na lista de clientes e selecione Conta.Select the customer from the customer list, then select Account. Na página Conta do cliente, procure a ID da Microsoft na seção Informações da Conta do Cliente.On the customer’s Account page, look for the Microsoft ID in the Customer Account Info section. A ID da Microsoft é igual à ID do cliente (customer-tenant-id).The Microsoft ID is the same as the customer ID (customer-tenant-id).

  • Uma ID de assinatura.A subscription ID. Esta é a assinatura existente para a qual comprar uma oferta de complemento.This is the existing subscription for which to purchase an add-on offer.

  • Uma ID de oferta que identifica a oferta de complemento a ser comprada.An offer ID that identifies the add-on offer to purchase.

Comprando um complemento por meio de códigoPurchasing an add-on through code

Ao comprar um complemento para uma assinatura, você está atualizando a ordem de assinatura original com a ordem do complemento.When you purchase an add-on to a subscription you are updating the original subscription order with the order for the add-on. No seguinte, customerId é a ID do cliente, SubscriptionId é a ID da assinatura e addOnOfferId é a ID da oferta do complemento.In the following, customerId is the customer ID, subscriptionId is the subscription ID, and addOnOfferId is the offer ID for the add-on.

Aqui estão as etapas para fazer isso:Here are the steps:

  1. Obtenha uma interface para as operações da assinatura.Get an interface to the operations for the subscription.

    var subscriptionOperations = partnerOperations.Customers.ById(customerId).Subscriptions.ById(subscriptionId);
    
  2. Use essa interface para criar uma instância de um objeto de assinatura.Use that interface to instantiate a subscription object. Isso obtém os detalhes da assinatura pai, incluindo a ID do pedido.This gets you the parent subscription details, including the order id.

    var parentSubscription = subscriptionOperations.Get();
    
  3. Crie uma instância de um novo objeto de pedido .Instantiate a new Order object. Essa instância de ordem é usada para atualizar a ordem original usada para comprar a assinatura.This order instance is used to update the original order used to purchase the subscription. Adicione um único item de linha à ordem que representa o complemento.Add a single line item to the order that represents the add-on.

    var orderToUpdate = new Order()
    {
        ReferenceCustomerId = customerId,
        LineItems = new List<OrderLineItem>()
        {
            new OrderLineItem()
            {
                LineItemNumber = 0,
                OfferId = addOnOfferId,
                FriendlyName = "Some friendly name",
                Quantity = 2,
                ParentSubscriptionId = subscriptionId
            }
        }
    };
    
  4. Atualize o pedido original para a assinatura com o novo pedido para o complemento.Update the original order for the subscription with the new order for the add-on.

    Order updatedOrder = partnerOperations.Customers.ById(customerId).Orders.ById(parentSubscription.OrderId).Patch(orderToUpdate);
    

C#C#

Para comprar um complemento, comece obtendo uma interface para as operações de assinatura chamando o método IAggregatePartner. Customers. ById com a ID do cliente para identificar o cliente e o método subscriptions . ById para identificar a assinatura que tem a oferta de complemento.To purchase an add-on, begin by obtaining an interface to the subscription operations by calling the IAggregatePartner.Customers.ById method with the customer ID to identify the customer, and the Subscriptions.ById method to identify the subscription that has the add-on offer. Use essa interface para recuperar os detalhes da assinatura chamando Get.Use that interface to retrieve the subscription details by calling Get. Por que você precisa dos detalhes da assinatura?Why do you need the subscription details? Porque você precisa da ID da ordem da assinatura.Because you need the order id of the subscription order. Essa é a ordem a ser atualizada com o complemento.That's the order to be updated with the add-on.

Em seguida, instancie um novo objeto de pedido e preencha-o com uma única instância de LineItem que contém as informações para identificar o complemento, conforme mostrado no trecho de código a seguir.Next, instantiate a new Order object and populate it with a single LineItem instance that contains the information to identify the add-on, as shown in the following code snippet. Você usará esse novo objeto para atualizar a ordem de assinatura com o complemento.You'll use this new object to update the subscription order with the add-on. Por fim, chame o método patch para atualizar a ordem de assinatura, depois de primeiro identificar o cliente com IAggregatePartner. Customers. ById e a ordem com Orders. ById.Finally, call the Patch method to update the subscription order, after first identifying the customer with IAggregatePartner.Customers.ById and the order with Orders.ById.

// IAggregatePartner partnerOperations;
// string customerId;
// string subscriptionId;
// string addOnOfferId;

// Get an interface to the operations for the subscription.
var subscriptionOperations = partnerOperations.Customers.ById(customerId).Subscriptions.ById(subscriptionId);

// Get the parent subscription details.
var parentSubscription = subscriptionOperations.Get();

// In order to buy an add-on subscription for this offer, we need to patch/update the order through which the base offer was purchased
// by creating an order object with a single line item which represents the add-on offer purchase.
var orderToUpdate = new Order()
{
    ReferenceCustomerId = customerId,
    LineItems = new List<OrderLineItem>()
    {
        new OrderLineItem()
        {
            LineItemNumber = 0,
            OfferId = addOnOfferId,
            FriendlyName = "Some friendly name",
            Quantity = 2,
            ParentSubscriptionId = subscriptionId
        }
    }
};

// Update the order to apply the add on purchase.
Order updatedOrder = partnerOperations.Customers.ById(customerId).Orders.ById(parentSubscription.OrderId).Patch(orderToUpdate);

Exemplo: aplicativo de teste do console.Sample: Console test app. Projeto: classede exemplos do SDK do Partner Center: AddSubscriptionAddOn.csProject: Partner Center SDK Samples Class: AddSubscriptionAddOn.cs

Solicitação RESTREST request

Sintaxe da solicitaçãoRequest syntax

MétodoMethod URI da solicitaçãoRequest URI
DISTRIBUÍDOPATCH {baseURL}/v1/Customers/{Customer-Tenant-ID}/Orders/{Order-ID} http/1.1{baseURL}/v1/customers/{customer-tenant-id}/orders/{order-id} HTTP/1.1

Parâmetros do URIURI parameters

Use os parâmetros a seguir para identificar o cliente e o pedido.Use the following parameters to identify the customer and order.

NomeName TipoType ObrigatórioRequired DescriçãoDescription
customer-tenant-idcustomer-tenant-id guidguid SY O valor é um GUID formatado Customer-Tenant-ID que identifica o cliente.The value is a GUID formatted customer-tenant-id that identifies the customer.
ID do pedidoorder-id guidguid SY O identificador do pedido.The order identifier.

Cabeçalhos de solicitaçãoRequest headers

Para obter mais informações, confira Cabeçalhos REST do Partner Center.For more information, see Partner Center REST headers.

Corpo da solicitaçãoRequest body

As tabelas a seguir descrevem as propriedades no corpo da solicitação.The following tables describe the properties in the request body.

OrderOrder

NomeName TipoType ObrigatórioRequired DescriçãoDescription
IDId stringstring NN A ID do pedido.The order ID.
ReferenceCustomerIdReferenceCustomerId stringstring SY O ID do cliente.The customer ID.
LineItemsLineItems matriz de objetosarray of objects SY Uma matriz de objetos OrderLineItem .An array of OrderLineItem objects.
CreationDateCreationDate stringstring NN A data em que o pedido foi criado, no formato de data e hora.The date the order was created, in date-time format.
AtributosAttributes objetoobject NN Contém "ObjectType": "Order".Contains "ObjectType": "Order".

OrderLineItemOrderLineItem

NomeName TipoType ObrigatórioRequired DescriçãoDescription
LineItemNumberLineItemNumber númeronumber SY O número do item de linha, começando com 0.The line item number, starting with 0.
OfferIdOfferId stringstring SY A ID da oferta do complemento.The offer ID of the add-on.
SubscriptionIdSubscriptionId stringstring NN A ID da assinatura do complemento adquirida.The ID of the add-on subscription purchased.
ParentSubscriptionIdParentSubscriptionId stringstring SY A ID da assinatura pai que tem a oferta de complemento.The ID of the parent subscription that has the add-on offer.
FriendlyNameFriendlyName stringstring NN O nome amigável para este item de linha.The friendly name for this line item.
QuantidadeQuantity númeronumber SY O número de licenças.The number of licenses.
PartnerIdOnRecordPartnerIdOnRecord stringstring NN A ID de MPN do parceiro de registro.The MPN ID of the partner of record.
AtributosAttributes objetoobject NN Contém "ObjectType": "OrderLineItem".Contains "ObjectType": "OrderLineItem".

Exemplo de solicitaçãoRequest example

PATCH https://api.partnercenter.microsoft.com/v1/customers/4d3cf487-70f4-4e1e-9ff1-b2bfce8d9f04/orders/CF3B0E37-BE0B-4CDD-B584-D1A97D98A922 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 17a2658e-d2cc-439b-a2f0-2aefd9344fbc
MS-CorrelationId: 60efdd24-17ef-4080-9b02-4fc315f916ff
X-Locale: en-US
Content-Type: application/json
Host: api.partnercenter.microsoft.com
Content-Length: 414
Expect: 100-continue

{
    "Id": null,
    "ReferenceCustomerId": "4d3cf487-70f4-4e1e-9ff1-b2bfce8d9f04",
    "LineItems": [{
            "LineItemNumber": 0,
            "OfferId": "2828BE95-46BA-4F91-B2FD-0BEF192ECF60",
            "SubscriptionId": null,
            "ParentSubscriptionId": "1C2B75C1-74A5-472A-A729-7F8CEFC477F9",
            "FriendlyName": "Some friendly name",
            "Quantity": 2,
            "PartnerIdOnRecord": null,
            "Attributes": {
                "ObjectType": "OrderLineItem"
            }
        }
    ],
    "CreationDate": null,
    "Attributes": {
        "ObjectType": "Order"
    }
}

Resposta RESTREST response

Se for bem-sucedido, esse método retornará a ordem de assinatura atualizada no corpo da resposta.If successful, this method returns the updated subscription order in the response body.

Códigos de êxito e de erro de respostaResponse success and error codes

Cada resposta vem com um código de status HTTP que indica êxito ou falha e informações de depuração adicionais.Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use uma ferramenta de rastreamento de rede para ler esse código, o tipo de erro e os parâmetros adicionais.Use a network trace tool to read this code, error type, and additional parameters. Para obter a lista completa, consulte códigos de erro do Partner Center.For the full list, see Partner Center Error Codes.

Exemplo de respostaResponse example

HTTP/1.1 200 OK
Content-Length: 1135
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 60efdd24-17ef-4080-9b02-4fc315f916ff
MS-RequestId: 17a2658e-d2cc-439b-a2f0-2aefd9344fbc
MS-CV: WtFy3zI8V0u2lnT9.0
MS-ServerId: 020021921
Date: Wed, 25 Jan 2017 23:01:08 GMT

{
    "id": "cf3b0e37-be0b-4cdd-b584-d1a97d98a922",
    "referenceCustomerId": "4d3cf487-70f4-4e1e-9ff1-b2bfce8d9f04",
    "billingCycle": "none",
    "lineItems": [{
            "lineItemNumber": 0,
            "offerId": "195416C1-3447-423A-B37B-EE59A99A19C4",
            "subscriptionId": "1C2B75C1-74A5-472A-A729-7F8CEFC477F9",
            "friendlyName": "new offer purchase",
            "quantity": 5,
            "links": {
                "subscription": {
                    "uri": "/customers/4d3cf487-70f4-4e1e-9ff1-b2bfce8d9f04/subscriptions/1C2B75C1-74A5-472A-A729-7F8CEFC477F9",
                    "method": "GET",
                    "headers": []
                }
            }
        }, {
            "lineItemNumber": 1,
            "offerId": "2828BE95-46BA-4F91-B2FD-0BEF192ECF60",
            "subscriptionId": "968BA1CF-C146-4ADF-A300-308DCF718EEE",
            "friendlyName": "Some friendly name",
            "quantity": 2,
            "links": {
                "subscription": {
                    "uri": "/customers/4d3cf487-70f4-4e1e-9ff1-b2bfce8d9f04/subscriptions/968BA1CF-C146-4ADF-A300-308DCF718EEE",
                    "method": "GET",
                    "headers": []
                }
            }
        }
    ],
    "creationDate": "2017-01-25T14:53:12.093-08:00",
    "links": {
        "self": {
            "uri": "/customers/4d3cf487-70f4-4e1e-9ff1-b2bfce8d9f04/orders/cf3b0e37-be0b-4cdd-b584-d1a97d98a922",
            "method": "GET",
            "headers": []
        }
    },
    "attributes": {
        "etag": "eyJpZCI6ImNmM2IwZTM3LWJlMGItNGNkZC1iNTg0LWQxYTk3ZDk4YTkyMiIsInZlcnNpb24iOjJ9",
        "objectType": "Order"
    }
}