Compartilhar via

Gerenciar linhas de entrega

  • Artigo

Use esses métodos na API de promoções da Microsoft Store para criar uma ou mais linhas de entrega para comprar inventário e entregar seus anúncios para uma campanha publicitária promocional. Para cada linha de exibição, você pode definir a segmentação, definir o preço do lance e decidir quanto deseja gastar definindo um orçamento e vinculando aos criativos que deseja usar.

Para obter mais informações sobre a relação entre linhas de entrega e campanhas publicitárias, perfis de segmentação e criativos, consulte Executar campanhas publicitárias usando os serviços da Microsoft Store.

Observação Antes de criar com êxito linhas de entrega para campanhas publicitárias usando essa API, você deve primeiro criar uma campanha publicitária paga usando a página Campanhas publicitárias no Partner Center e adicionar pelo menos um instrumento de pagamento nessa página. Depois de fazer isso, você poderá criar com êxito linhas de entrega faturáveis para campanhas publicitárias usando essa API. As campanhas publicitárias que você criar usando a API cobrarão automaticamente o instrumento de pagamento padrão escolhido na página Campanhas publicitárias no Partner Center.

Pré-requisitos

Para usar esses métodos, primeiro você precisa fazer o seguinte:

  • Se você ainda não fez isso, conclua todos os pré-requisitos para a API de promoções da Microsoft Store.

    Observação

    Como parte dos pré-requisitos, certifique-se de criar pelo menos uma campanha publicitária paga no Partner Center e adicionar pelo menos um instrumento de pagamento para a campanha publicitária no Partner Center. As linhas de entrega criadas usando essa API cobrarão automaticamente o instrumento de pagamento padrão escolhido na página Campanhas publicitárias no Partner Center.

  • Obtenha um token de acesso do Azure AD para usar no cabeçalho de solicitação para esses métodos. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá obter um novo.

Solicitação

Esses métodos têm as URIs a seguir.

Tipo de método URI da solicitação Descrição
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line Cria uma nova linha de entrega.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Edita a linha de entrega especificada por lineId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Obtém a linha de entrega especificada por lineId.
parâmetro Tipo Descrição
Autorização string Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário.
ID de rastreamento GUID Opcional. Uma ID que rastreia o fluxo de chamadas.

Corpo da solicitação

Os métodos POST e PUT exigem um corpo de solicitação JSON com os campos obrigatórios de um objeto de linha Delivery e quaisquer campos adicionais que você deseja definir ou alterar.

Exemplos de solicitação

O exemplo a seguir demonstra como chamar o método POST para criar uma linha de entrega.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign - Paid Line",
    "configuredStatus": "Active",
    "startDateTime": "2017-01-19T12:09:34Z",
    "endDateTime": "2017-01-31T23:59:59Z",
    "bidAmount": 0.4,
    "dailyBudget": 20,
    "targetProfileId": {
        "id": 310021746
    },
    "creatives": [
        {
            "id": 106851
        }
    ],
    "campaignId": 31043481,
    "minMinutesPerImp ": 1
}

O exemplo a seguir demonstra como chamar o método GET para recuperar uma linha de entrega.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/31019990  HTTP/1.1
Authorization: Bearer <your access token>

Resposta

Esses métodos retornam um corpo de resposta JSON com um objeto de linha Delivery que contém informações sobre a linha de entrega que foi criada, atualizada ou recuperada. O exemplo a seguir demonstra um corpo de resposta para esses métodos.

{
    "Data": {
        "id": 31043476,
        "name": "Contoso App Campaign - Paid Line",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "startDateTime": "2017-01-19T12:09:34Z",
        "endDateTime": "2017-01-31T23:59:59Z",
        "createdDateTime": "2017-01-17T10:28:34Z",
        "bidType": "CPM",
        "bidAmount": 0.4,
        "dailyBudget": 20,
        "targetProfileId": {
            "id": 310021746
        },
        "creatives": [
            {
                "id": 106126
            }
        ],
        "campaignId": 31043481,
        "minMinutesPerImp ": 1,
        "pacingType ": "SpendEvenly",
        "currencyId ": 732
    }
}

Objeto de linha de entrega

Os corpos de solicitação e resposta para esses métodos contêm os campos a seguir. Esta tabela mostra quais campos são somente leitura (o que significa que eles não podem ser alterados no método PUT) e quais campos são obrigatórios no corpo da solicitação para os métodos POST ou PUT.

Campo Type Description Somente leitura Padrão Necessário para POST/PUT
ID Número inteiro A ID da linha de entrega. Sim Não
name string O nome da linha de entrega. Não POSTAR
Status configurado string Um dos seguintes valores que especifica o status da linha de entrega especificada pelo desenvolvedor:
  • Com atividade
  • Inativo
 Não POSTAR
status efetivo string Um dos seguintes valores que especifica o status efetivo da linha de entrega com base na validação do sistema:
  • Com atividade
  • Inativo
  • Em processamento
  • Com falha
 Sim No
effectiveStatusReasons matriz Um ou mais dos seguintes valores que especificam o motivo do status efetivo da linha de entrega:
  • AnúnciosCriativosInativo
  • Falha na validação
 Sim No
data inicial string A data e hora de início da linha de entrega, no formato ISO 8601. Esse valor não pode ser alterado se já estiver no passado. Não POSTAR, COLOCAR
data e hora finais string A data e hora de término da linha de entrega, no formato ISO 8601. Esse valor não pode ser alterado se já estiver no passado. Não POSTAR, COLOCAR
createdDatetime string A data e a hora em que a linha de entrega foi criada, no formato ISO 8601. Sim No
tipo de oferta string Um valor que especifica o tipo de lance da linha de entrega. Atualmente, o único valor suportado é o CPM. Não CPM Não
valor do lance decimal O valor do lance a ser usado para dar lances em qualquer solicitação de anúncio. Não O valor médio do CPM com base nos mercados-alvo (esse valor é revisado periodicamente). Não
dailyBudget decimal O orçamento diário para a linha de entrega. DailyBudget ou lifetimeBudget devem ser definidos. Não POST, PUT (se lifetimeBudget não estiver definido)
Orçamento vitalício decimal O orçamento vitalício para a linha de entrega. LifetimeBudget* ou dailyBudget devem ser definidos. Não POST, PUT (se dailyBudget não estiver definido)
targetingProfileId objeto On que identifica o perfil de segmentação que descreve os usuários, as regiões geográficas e os tipos de inventário que você deseja direcionar para essa linha de entrega. Esse objeto consiste em um único campo de id que especifica o ID do perfil de segmentação. Não No
criativos matriz Um ou mais objetos que representam os criativos associados à linha de exibição. Cada objeto nesse campo consiste em um único campo de código que especifica o código de um criativo. Não No
campaignId Número inteiro O ID da campanha publicitária principal. Não No
minMinutesPerImp Número inteiro Especifica o intervalo de tempo mínimo (em minutos) entre duas impressões exibidas para o mesmo usuário dessa linha de exibição. Não 4000 Não
tipo de ritmo string Um dos seguintes valores que especificam o tipo de espaçamento:
  • GasteUniformemente
  • GasteAsFastAsPossible
 Não GasteUniformemente Não
currencyId Número inteiro O ID da moeda da campanha. Sim A moeda da conta de desenvolvedor (você não precisa especificar esse campo em chamadas POST ou PUT) Não