Ausführen von Ad-Kampagnen mithilfe von Store ServicesRun ad campaigns using Store services

Verwenden Sie die Microsoft Store Promotions-API , um Werbekampagnen für Werbeaktionen für Apps Programm gesteuert zu verwalten, die für das Partner Center-Konto Ihrer Organisation registriert sind.Use the Microsoft Store promotions API to programmatically manage promotional ad campaigns for apps that are registered to your or your organization's Partner Center account. Diese API ermöglicht Ihnen das Erstellen, aktualisieren und Überwachen von Kampagnen und anderen verwandten Ressourcen, z. b. Ziel-und Erstellungs Aktionen.This API enables you to create, update and monitor your campaigns and other related assets such as targeting and creatives. Diese API ist besonders nützlich für Entwickler, die große Mengen von Kampagnen erstellen und ohne Partner Center verwenden möchten.This API is especially useful for developers who create large volumes of campaigns, and who want to do so without using Partner Center. Diese API verwendet Azure Active Directory (Azure AD), um die Aufrufe von Ihrer App oder Ihrem Dienst zu authentifizieren.This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

Dazu müssen folgende Schritte ausgeführt werden:The following steps describe the end-to-end process:

  1. Stellen Sie sicher, dass Sie alle Voraussetzungen erfüllt haben.Make sure that you have completed all the prerequisites.
  2. Bevor Sie eine Methode in der Microsoft Store promotionapi aufrufen, erhalten Sie ein Azure AD Zugriffs Token.Before you call a method in the Microsoft Store promotions API, obtain an Azure AD access token. Nachdem Sie ein Token erhalten haben, haben Sie 60 Minuten Zeit, dieses Token in Aufrufen der Microsoft Store promotionapi zu verwenden, bevor das Token abläuft.After you obtain a token, you have 60 minutes to use this token in calls to the Microsoft Store promotions API before the token expires. Nach dem Ablauf des Tokens können Sie ein neues Token generieren.After the token expires, you can generate a new token.
  3. Nennen Sie die Microsoft Store promotionapi.Call the Microsoft Store promotions API.

Alternativ können Sie Ad-Kampagnen mithilfe von Partner Center erstellen und verwalten, und alle Werbekampagnen, die Sie Programm gesteuert über die Microsoft Store promotionapi erstellen, können auch im Partner Center aufgerufen werden.You can alternatively create and manage ad campaigns using Partner Center, and any ad campaigns that you create programmatically via the Microsoft Store promotions API can also be accessed in Partner Center. Weitere Informationen zum Verwalten von Ad-Kampagnen in Partner Center finden Sie unter Erstellen einer AD-Kampagne für Ihre APP.For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

Hinweis

Alle Entwickler mit einem Partner Center-Konto können die Microsoft Store promotionapi verwenden, um Werbekampagnen für Ihre apps zu verwalten.Any developer with a Partner Center account can use the Microsoft Store promotions API to manage ad campaigns for their apps. Medien Behörden können auch Zugriff auf diese API anfordern, um Werbekampagnen im Namen Ihrer Werbespots auszuführen.Media agencies can also request access to this API to run ad campaigns on behalf of their advertisers. Wenn Sie eine Medienbehörde sind, die mehr über diese API erfahren oder Zugriff darauf anfordern möchte, senden Sie Ihre Anforderung an storepromotionsapi@microsoft.com .If you are a media agency who wants to know more about this API or request access to it, send your request to storepromotionsapi@microsoft.com.

Schritt 1: Voraussetzungen für die Verwendung der Microsoft Store Promotions-APIStep 1: Complete prerequisites for using the Microsoft Store promotions API

Vergewissern Sie sich, dass die folgenden Voraussetzungen erfüllt sind, bevor Sie mit dem Schreiben von Code beginnen, um die Microsoft Store promotionapi aufzurufen.Before you start writing code to call the Microsoft Store promotions API, make sure that you have completed the following prerequisites.

  • Bevor Sie mit dieser API eine AD-Kampagne erstellen und starten können, müssen Sie zunächst auf der Seite mit den Werbekampagnen im Partner Center eine bezahlte Werbekampagne erstellen, und Sie müssen mindestens ein Zahlungsinstrument auf dieser Seite hinzufügen.Before you can successfully create and start an ad campaign using this API, you must first create one paid ad campaign using the Ad campaigns page in Partner Center, and you must add at least one payment instrument on this page. Nachdem Sie dies getan haben, können Sie mithilfe dieser API abrechenbare Übermittlungs Zeilen für Ad-Kampagnen erstellen.After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. Mit Übermittlungs Zeilen für Ad-Kampagnen, die Sie mit dieser API erstellen, wird automatisch das standardmäßige Zahlungsinstrument abgerechnet, das auf der Seite mit den Werbekampagnen im Partner CenterDelivery lines for ad campaigns you create using this API will automatically bill the default payment instrument chosen on the Ad campaigns page in Partner Center.

  • Sie (oder Ihre Organisation) müssen über ein Azure AD-Verzeichnis verfügen, und Ihnen müssen die Berechtigungen globaler Administrator für das Verzeichnis gewährt worden sein.You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. Wenn Sie Microsoft 365 oder andere Unternehmensdienste von Microsoft verwenden, verfügen Sie bereits über ein Azure AD-Verzeichnis.If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory. Andernfalls können Sie eine neue Azure AD im Partner Center erstellen , ohne dass zusätzliche Kosten anfallen.Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • Sie müssen Ihrem Partner Center-Konto eine Azure AD Anwendung zuordnen, die Mandanten-ID und die Client-ID für die Anwendung abrufen und einen Schlüssel generieren.You must associate an Azure AD application with your Partner Center account, retrieve the tenant ID and client ID for the application and generate a key. Die Azure AD-Anwendung stellt die APP oder den Dienst dar, von dem aus Sie die Microsoft Store promotionapi abrufen möchten.The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. Sie benötigen die Mandanten-ID, die Client-ID und den Schlüssel, um ein Azure AD-Zugriffstoken zu erhalten, das Sie an die API übergeben.You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    Hinweis

    Sie müssen diese Aufgabe nur einmal ausführen.You only need to perform this task one time. Nachdem Sie über die Mandanten-ID, die Client-ID und den Schlüssel verfügen, können Sie diese jederzeit wiederverwenden, wenn Sie ein neues Azure AD-Zugriffstoken erstellen müssen.After you have the tenant ID, client ID and key, you can reuse them any time you need to create a new Azure AD access token.

So ordnen Sie eine Azure AD Anwendung Ihrem Partner Center-Konto zu und rufen die erforderlichen Werte ab:To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. Verknüpfen Sie in Partner Center das Partner Center-Konto Ihres Unternehmens mit dem Azure AD-Verzeichnis Ihrer Organisation.In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. Fügen Sie als nächstes auf der Seite " Benutzer " im Abschnitt " Kontoeinstellungen " von Partner Center die Azure AD Anwendung hinzu , die die APP oder den Dienst darstellt, die Sie zum Verwalten von Promotionkampagnen für Ihr Partner Center-Konto verwenden.Next, from the Users page in the Account settings section of Partner Center, add the Azure AD application that represents the app or service that you will use to manage promotion campaigns for your Partner Center account. Stellen Sie sicher, dass Sie dieser Anwendung die Rolle Manager zuweisen.Make sure you assign this application the Manager role. Wenn die Anwendung noch nicht in Ihrem Azure AD-Verzeichnis vorhanden ist, können Sie in Partner Center eine neue Azure AD-Anwendung erstellen.If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. Kehren Sie zur Seite Benutzer zurück, klicken Sie auf den Namen Ihrer Azure AD-Anwendung, um die Anwendungseinstellungen zu öffnen, und schreiben Sie die Werte Mandanten-ID und Client-ID auf.Return to the Users page, click the name of your Azure AD application to go to the application settings, and copy down the Tenant ID and Client ID values.

  4. Klicken Sie auf Neuen Schlüssel hinzufügen.Click Add new key. Notieren Sie auf dem folgenden Bildschirm den Wert von Schlüssel.On the following screen, copy down the Key value. Nachdem Sie diese Seite verlassen haben, können Sie nicht mehr auf diese Informationen zugreifen.You won't be able to access this info again after you leave this page. Weitere Informationen finden Sie unter Verwalten von Schlüsseln für eine Azure AD-Anwendung.For more information, see Manage keys for an Azure AD application.

Schritt 2: Abrufen eines Azure AD-ZugriffstokensStep 2: Obtain an Azure AD access token

Bevor Sie eine der Methoden in der Microsoft Store promotionapi aufrufen, müssen Sie zuerst ein Azure AD Zugriffs Token abrufen, das Sie an den Autorisierungs Header jeder Methode in der API übergeben.Before you call any of the methods in the Microsoft Store promotions API, you must first obtain an Azure AD access token that you pass to the Authorization header of each method in the API. Nachdem Sie ein Zugriffstoken erhalten haben, haben Sie 60 Minuten Zeit, es zu verwenden, bevor es abläuft.After you obtain an access token, you have 60 minutes to use it before it expires. Nachdem das Token abgelaufen ist, können Sie es aktualisieren, um es in weiteren Aufrufen an die API zu verwenden.After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

Befolgen Sie zum Abrufen des Zugriffstokens die Anweisungen unter Aufrufe zwischen Diensten mithilfe von Clientanmeldeinformationen, um eine HTTP POST-Anforderung an den https://login.microsoftonline.com/<tenant_id>/oauth2/token-Endpunkt zu senden.To obtain the access token, follow the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. Hier ist ein Beispiel für eine Anforderung angegeben.Here is a sample request.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://manage.devcenter.microsoft.com

Geben Sie als Mandanten- * _ ID* im Post-URI und in den Parametern für die Client- _ ID und den * _ geheimen Client* Schlüssel die Mandanten-ID, die Client-ID und den Schlüssel für die Anwendung an, die Sie im vorherigen Abschnitt aus Partner Center abgerufen haben.For the tenant_id value in the POST URI and the client_id and client_secret parameters, specify the tenant ID, client ID and the key for your application that you retrieved from Partner Center in the previous section. Für den Parameter resource müssen Sie https://manage.devcenter.microsoft.com angeben.For the resource parameter, you must specify https://manage.devcenter.microsoft.com.

Nachdem das Zugriffstoken abgelaufen ist, können Sie es aktualisieren, indem Sie diese Anleitung befolgen.After your access token expires, you can refresh it by following the instructions here.

Schritt 3: Abrufen der Microsoft Store promotionapiStep 3: Call the Microsoft Store promotions API

Nachdem Sie über ein Azure AD Zugriffs Token verfügen, können Sie die Microsoft Store promotionapi aufrufen.After you have an Azure AD access token, you are ready to call the Microsoft Store promotions API. Sie müssen das Zugriffstoken an den Authorization-Header der einzelnen Methoden übergeben.You must pass the access token to the Authorization header of each method.

Im Zusammenhang mit der Microsoft Store promotionapi besteht eine Werbekampagne aus einem Kampagnen Objekt, das allgemeine Informationen über die Kampagne enthält , sowie zusätzlichen Objekten, die die Übermittlungs Zeilen, Ziel profileund Erstellungen für die Werbekampagne darstellen.In the context of the Microsoft Store promotions API, an ad campaign consists of a campaign object that contains high-level information about the campaign, and additional objects that represent the delivery lines, targeting profiles, and creatives for the ad campaign. Die API umfasst unterschiedliche Sätze von Methoden, die nach diesen Objekttypen gruppiert sind.The API includes different sets of methods that are grouped by these object types. Zum Erstellen einer Kampagne rufen Sie in der Regel eine andere Post-Methode für jedes dieser Objekte auf.To create a campaign, you typically call a different POST method for each of these objects. Die API stellt auch Get-Methoden bereit, mit denen Sie beliebige Objekte und Put-Methoden abrufen können, die Sie zum Bearbeiten von Kampagnen-, Übermittlungs Zeilen-und Ziel Profil Objekten verwenden können.The API also provides GET methods you can use to retrieve any object and PUT methods you can use to edit campaign, delivery line, and targeting profile objects.

Weitere Informationen zu diesen Objekten und den zugehörigen Methoden finden Sie in der folgenden Tabelle.For more information about these objects and their related methods, see the following table.

ObjectObject BESCHREIBUNGDescription
KampagnenCampaigns Dieses Objekt stellt die AD-Kampagne dar und befindet sich oben in der Objektmodell Hierarchie für Ad-Kampagnen.This object represents the ad campaign, and it sits at the top of the object model hierarchy for ad campaigns. Dieses Objekt identifiziert den Typ der Kampagne, die Sie ausführen (bezahlt, Haus oder Community), das Kampagnenziel, die Übermittlungs Zeilen für die Kampagne und weitere Details.This object identifies the type of campaign you are running (paid, house, or community), the campaign objective, the delivery lines for the campaign, and other details. Jede Kampagne kann nur einer APP zugeordnet werden.Each campaign can be associated with only one app.

Weitere Informationen zu den Methoden, die sich auf dieses Objekt beziehen, finden Sie unter Verwalten von Ad-Kampagnen.For more information about the methods related to this object, see Manage ad campaigns.

Note   Hinweis   Nachdem Sie eine Werbekampagne erstellt haben, können Sie die Leistungsdaten für die Kampagne abrufen, indem Sie die Leistungsdaten Methode "AD-Kampagne abrufen" in der Microsoft Store Analytics-APIverwenden.Note  After you create an ad campaign, you can retrieve performance data for the campaign by using the Get ad campaign performance data method in the Microsoft Store analytics API.
Übermittlungs ZeilenDelivery lines Jede Kampagne verfügt über eine oder mehrere Übermittlungs Zeilen, mit denen Sie Inventar kaufen und ihre Werbeeinblendungen bereitstellen können.Every campaign has one or more delivery lines that are used to buy inventory and deliver your ads. Für jede Übermittlungs Zeile können Sie die Zielgruppe festlegen, ihren Angebotspreis festlegen und entscheiden, wie viel Geld Sie aufwenden möchten, indem Sie ein Budget festlegen und mit den gewünschten Informationen verknüpfen.For each delivery line, you can set targeting, set your bid price, and decide how much you want to spend by setting a budget and linking to creatives you want to use.

Weitere Informationen zu den Methoden, die sich auf dieses Objekt beziehen, finden Sie unter Verwalten von Übermittlungs Zeilen für Werbekampagnen.For more information about the methods related to this object, see Manage delivery lines for ad campaigns.
Ziel profileTargeting profiles Jede Übermittlungs Zeile verfügt über ein Ziel Profil, das die Benutzer, Regionen und Inventur Typen angibt, auf die Sie abzielen möchten.Every delivery line has one targeting profile that specifies the users, geographies and inventory types that you want to target. Ziel Profile können als Vorlage erstellt und über die Übermittlungs Zeilen hinweg freigegeben werden.Targeting profiles can be created as a template and shared across delivery lines.

Weitere Informationen zu den Methoden, die mit diesem Objekt verknüpft sind, finden Sie unter Verwalten von Ziel Profilen für Ad-Kampagnen.For more information about the methods related to this object, see Manage targeting profiles for ad campaigns.
-KreativeCreatives Jede Übermittlungs Zeile verfügt über mindestens ein-Element, das die Werbeeinblendungen darstellt, die Kunden im Rahmen der Kampagne angezeigt werden.Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. Ein Creative-Vorgang kann mit einer oder mehreren Übermittlungs Zeilen verknüpft werden, auch bei Ad-Kampagnen, sofern er immer dieselbe APP darstellt.A creative may be associated with one or more delivery lines, even across ad campaigns, provided it always represents the same app.

Weitere Informationen zu den Methoden, die mit diesem Objekt verknüpft sind, finden Sie unter Verwalten von krektionen für Werbekampagnen.For more information about the methods related to this object, see Manage creatives for ad campaigns.

Das folgende Diagramm veranschaulicht die Beziehung zwischen Kampagnen, Übermittlungs Zeilen, Ziel Profilen und Erstellungen.The following diagram illustrates the relationship between campaigns, delivery lines, targeting profiles, and creatives.

Ad-Kampagnen Hierarchie

CodebeispielCode example

Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein Azure AD Zugriffs Token abrufen und die Microsoft Store promotionapi aus einer c#-Konsolen-App aufrufen.The following code example demonstrates how to obtain an Azure AD access token and call the Microsoft Store promotions API from a C# console app. Wenn Sie dieses Codebeispiel verwenden möchten, weisen Sie die Variablen TenantId, ClientId, ClientSecret und AppID den entsprechenden Werten für Ihr Szenario zu.To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. Für dieses Beispiel ist es erforderlich, dass das JSON.net-Paket von newtonsoft die von der Microsoft Store promotionapi zurückgegebenen JSON-Daten deserialisiert.This example requires the Json.NET package from Newtonsoft to deserialize the JSON data returned by the Microsoft Store promotions API.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace TestPromotionsAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            string tenantId = "<your tenant ID>";
            string clientId = "<your client ID>";
            string clientSecret = "<your secret>";

            string scope = "https://manage.devcenter.microsoft.com";

            // Retrieve an Azure AD access token
            string accessToken = GetClientCredentialAccessToken(
                    tenantId,
                    clientId,
                    clientSecret,
                    scope).Result;

            int pageSize = 100;
            int startPageIndex = 0;

            // This is your app's Store ID. This ID is available on
            // the App identity page of the Dev Center dashboard.
            string appID = "<your app's Store ID>";


            // Call the Windows Store promotions API
            CallPromotionsAPI(accessToken, appID, pageSize, startPageIndex);

            Console.Read();
        }

        private static void CallPromotionsAPI(string accessToken, string appID, int fetch, int skip)
        {
            string requestURI;

            // Get ad campaigns.
            requestURI = string.Format(
                "https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?applicationId={0}&fetch={1}&skip={2}&campaignSetSortColumn=createdDateTime",
                appID, fetch, skip);

            HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, requestURI);
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            WebRequestHandler handler = new WebRequestHandler();
            HttpClient httpClient = new HttpClient(handler);

            HttpResponseMessage response = httpClient.SendAsync(requestMessage).Result;

            Console.WriteLine(response);
            Console.WriteLine(response.Content.ReadAsStringAsync().Result);

            response.Dispose();
        }

        public static async Task<string> GetClientCredentialAccessToken(string tenantId, string clientId, string clientSecret, string scope)
        {
            string tokenEndpointFormat = "https://login.microsoftonline.com/{0}/oauth2/token";
            string tokenEndpoint = string.Format(tokenEndpointFormat, tenantId);

            dynamic result;
            using (HttpClient client = new HttpClient())
            {
                string tokenUrl = tokenEndpoint;
                using (
                    HttpRequestMessage request = new HttpRequestMessage(
                        HttpMethod.Post,
                        tokenUrl))
                {
                    string content =
                        string.Format(
                            "grant_type=client_credentials&client_id={0}&client_secret={1}&resource={2}",
                            clientId,
                            clientSecret,
                            scope);

                    request.Content = new StringContent(content, Encoding.UTF8, "application/x-www-form-urlencoded");

                    using (HttpResponseMessage response = await client.SendAsync(request))
                    {
                        string responseContent = await response.Content.ReadAsStringAsync();
                        result = JsonConvert.DeserializeObject(responseContent);
                    }
                }
            }

            return result.access_token;
        }
    }
}