Gérer les lignes de livraison

  • Article

Utilisez ces méthodes dans l’API de promotions du Microsoft Store pour créer une ou plusieurs lignes de livraison afin d’acheter un inventaire et de distribuer vos annonces pour une campagne publicitaire promotionnelle. Pour chaque ligne de livraison, vous pouvez définir le ciblage, définir le prix de votre offre et décider du montant que vous souhaitez dépenser en définissant un budget et en liant les créations que vous souhaitez utiliser.

Pour plus d’informations sur la relation entre les lignes de distribution et les campagnes publicitaires, les profils de ciblage et les créations, consultez Exécuter des campagnes publicitaires à l’aide des services du Microsoft Store.

Note Avant de pouvoir créer des lignes de distribution pour les campagnes publicitaires à l’aide de cette API, vous devez d’abord créer une campagne publicitaire payante à l’aide de la page Campagnes publicitaires de l’Espace partenaires, et vous devez ajouter au moins un instrument de paiement sur cette page. Après cela, vous serez en mesure de créer des lignes de distribution facturables pour les campagnes publicitaires à l’aide de cette API. Les campagnes publicitaires que vous créez à l’aide de l’API facturent automatiquement l’instrument de paiement par défaut choisi sur la page Campagnes publicitaires de l’Espace partenaires.

Prérequis

Pour utiliser ces méthodes, vous devez d’abord effectuer les opérations suivantes :

  • Si vous ne l’avez pas déjà fait, remplissez tous les prérequis pour l’API de promotions du Microsoft Store.

    Notes

    Dans le cadre des conditions préalables, veillez à créer au moins une campagne publicitaire payante dans l’Espace partenaires et à ajouter au moins un instrument de paiement pour la campagne publicitaire dans l’Espace partenaires. Les lignes de livraison que vous créez à l’aide de cette API facturent automatiquement l’instrument de paiement par défaut choisi sur la page Campagnes publicitaires de l’Espace partenaires.

  • Obtenez un jeton d’accès Azure AD à utiliser dans l’en-tête de requête pour ces méthodes. Une fois que vous avez récupéré le jeton d’accès, vous avez 60 minutes pour l’utiliser avant qu’il n’expire. Une fois le jeton arrivé à expiration, vous pouvez en obtenir un nouveau.

Requête

Ces méthodes ont les URI suivants.

Type de méthode URI de demande Description
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line Crée une ligne de livraison.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Modifie la ligne de livraison spécifiée par lineId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Obtient la ligne de livraison spécifiée par lineId.
En-tête Type Description
Autorisation string Obligatoire. Jeton d’accès Azure AD sous la formeJeton> du porteur<.
ID de suivi GUID facultatif. ID qui effectue le suivi du flux d’appels.

Corps de la demande

Les méthodes POST et PUT nécessitent un corps de requête JSON avec les champs obligatoires d’un objet de ligne de remise et tous les champs supplémentaires que vous souhaitez définir ou modifier.

Exemples de demande

L’exemple suivant montre comment appeler la méthode POST pour créer une ligne de remise.

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
}

L’exemple suivant montre comment appeler la méthode GET pour récupérer une ligne de remise.

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

response

Ces méthodes retournent un corps de réponse JSON avec un objet de ligne de remise qui contient des informations sur la ligne de remise qui a été créée, mise à jour ou récupérée. L’exemple suivant illustre un corps de réponse pour ces méthodes.

{
    "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
    }
}

Objet de ligne de livraison

Les corps de requête et de réponse pour ces méthodes contiennent les champs suivants. Ce tableau indique quels champs sont en lecture seule (ce qui signifie qu’ils ne peuvent pas être modifiés dans la méthode PUT) et quels champs sont requis dans le corps de la demande pour les méthodes POST ou PUT.

Champ Type Description Lecture seule Default Requis pour POST/PUT
id entier ID de la ligne de livraison. Oui Non
name string Nom de la ligne de livraison. Non POST
configureStatus string L’une des valeurs suivantes qui spécifie le status de la ligne de livraison spécifiée par le développeur :
  • Actif
  • Inactif
 Non POST
effectiveStatus string L’une des valeurs suivantes qui spécifie la status effective de la ligne de livraison en fonction de la validation du système :
  • Actif
  • Inactif
  • Traitement
  • Échec
 Oui Non
effectiveStatusReasons tableau Une ou plusieurs des valeurs suivantes qui spécifient la raison de la status effective de la ligne de livraison :
  • AdCreativesInactive
  • ValidationFailed
 Oui Non
startDatetime string Date et heure de début de la ligne de livraison, au format ISO 8601. Cette valeur ne peut pas être modifiée si elle est déjà dans le passé. Non POST, PUT
endDatetime string Date et heure de fin de la ligne de livraison, au format ISO 8601. Cette valeur ne peut pas être modifiée si elle est déjà dans le passé. Non POST, PUT
createdDatetime string Date et heure de création de la ligne de livraison, au format ISO 8601. Oui Non
bidType string Valeur qui spécifie le type d’enchère de la ligne de livraison. Actuellement, la seule valeur prise en charge est CPM. Non CPM Non
bidAmount Décimal Montant de l’offre à utiliser pour toute demande publicitaire. Non Valeur CPM moyenne en fonction des marchés cibles (cette valeur est révisée périodiquement). Non
dailyBudget Décimal Budget quotidien de la ligne de livraison. DailyBudget ou lifetimeBudget doit être défini. Non POST, PUT (si lifetimeBudget n’est pas défini)
lifetimeBudget Décimal Budget de durée de vie de la ligne de livraison. LifetimeBudget* ou dailyBudget doit être défini. Non POST, PUT (si dailyBudget n’est pas défini)
targetingProfileId object Objet qui identifie le profil de ciblage qui décrit les utilisateurs, les zones géographiques et les types d’inventaire que vous souhaitez cibler pour cette ligne de livraison. Cet objet se compose d’un seul champ ID qui spécifie l’ID du profil de ciblage. Non Non
Créatifs tableau Un ou plusieurs objets qui représentent les créations associées à la ligne de livraison. Chaque objet de ce champ se compose d’un seul champ ID qui spécifie l’ID d’un créateur. Non Non
campaignId entier ID de la campagne publicitaire parente. Non Non
minMinutesPerImp entier Spécifie l’intervalle de temps minimal (en minutes) entre deux impressions affichées pour le même utilisateur à partir de cette ligne de remise. Non 4000 Non
pacingType string Une des valeurs suivantes qui spécifient le type de rythme :
  • SpendEvenly
  • SpendAsFastAsPossible
 Non SpendEvenly Non
currencyId entier ID de la devise de la campagne. Oui Devise du compte de développeur (vous n’avez pas besoin de spécifier ce champ dans les appels POST ou PUT) Non