Ausführen von Anzeigenkampagnen mit Store-Diensten

Verwenden Sie die Microsoft Store-Promotions-API, um Werbeanzeigekampagnen für Apps programmgesteuert zu verwalten, die für Ihr Partner Center-Konto oder das Ihrer Organisation registriert sind. Mit dieser API können Sie Ihre Kampagnen und andere zugehörige Ressourcen wie Zielgruppenadressierung und Werbemittel erstellen, aktualisieren und überwachen. Diese API ist besonders nützlich für Entwickler, die große Mengen von Kampagnen erstellen und dies tun möchten, ohne Partner Center zu verwenden. Diese API verwendet Azure Active Directory (Azure AD), um die Aufrufe von Ihrer App oder Ihrem Dienst zu authentifizieren.

Die folgenden Schritte beschreiben den End-to-End-Prozess:

1. Stellen Sie sicher, dass Sie alle Voraussetzungenerfüllt haben.
2. Bevor Sie eine Methode in der Microsoft Store Promotions-API aufrufen, erhalten Sie ein Azure AD-Zugangs-Token. Nachdem Sie ein Token abgerufen haben, haben Sie 60 Minuten Zeit, dieses Token in Aufrufen der Microsoft Store-Werbungs-API zu verwenden, bevor das Token abläuft. Nach Ablauf des Tokens können Sie ein neues Token generieren.
3. Aufrufen der Microsoft Store-Werbungs-API.

Alternativ können Sie Anzeigenkampagnen mithilfe des Partner Centers erstellen und verwalten, und auf alle Anzeigenkampagnen, die Sie programmgesteuert über die Microsoft Store-Werbungs-API erstellen, kann auch im Partner Center zugegriffen werden. Weitere Informationen zum Verwalten von Anzeigenkampagnen im Partner Center finden Sie unter Erstellen einer Anzeigenkampagne für Ihre App-.

Anmerkung

Jeder Entwickler mit einem Partner Center-Konto kann die Microsoft Store-Werbungs-API verwenden, um Anzeigenkampagnen für ihre Apps zu verwalten. Medienagenturen können auch den Zugriff auf diese API anfordern, um Anzeigenkampagnen im Auftrag ihrer Werbekunden auszuführen. Wenn Sie eine Medienagentur sind, die mehr über diese API wissen möchte oder Den Zugriff darauf anfordern möchte, senden Sie Ihre Anforderung an storepromotionsapi@microsoft.com.

Schritt 1: Erfüllen der Voraussetzungen für die Verwendung der Microsoft Store-Werbungs-API

Bevor Sie mit dem Schreiben von Code zum Aufrufen der Microsoft Store-Werbungs-API beginnen, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllt haben.

• Bevor Sie eine Anzeigenkampagne mithilfe dieser API erfolgreich erstellen und starten können, müssen Sie zuerst eine kostenpflichtige Anzeigenkampagne mithilfe der Anzeigenkampagnen Seite im Partner Centererstellen und mindestens ein Zahlungsmittel auf dieser Seite hinzufügen. Anschließend können Sie mithilfe dieser API erfolgreich rechnungsbare Lieferpositionen für Anzeigenkampagnen erstellen. Die Lieferlinien für Werbekampagnen, die Sie mit dieser API erstellen, werden automatisch mit dem Standardzahlungsinstrument abgerechnet, das Sie auf der Seite Werbekampagnen im Partner Center ausgewählt haben.

• Sie (oder Ihre Organisation) müssen über ein Azure AD-Verzeichnis verfügen und über die Berechtigung eines globalen Administrators für das Verzeichnis verfügen. Wenn Sie Bereits Microsoft 365 oder andere Geschäftsdienste von Microsoft verwenden, verfügen Sie bereits über das Azure AD-Verzeichnis. Andernfalls können Sie einen neuen Azure AD im Partner Center ohne zusätzliche Gebühr erstellen.

• Sie müssen ihrer 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. Die Azure AD-Anwendung stellt die App oder den Dienst dar, aus der Sie die Microsoft Store-Werbungs-API aufrufen möchten. Sie benötigen die Mandanten-ID, die Client-ID und den Schlüssel, um ein Azure AD-Zugriffstoken abzurufen, das Sie an die API übergeben.

  Anmerkung

  Sie müssen diese Aufgabe nur einmal ausführen. 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.

So ordnen Sie eine Azure AD-Anwendung Ihrem Partner Center-Konto zu und rufen die erforderlichen Werte ab:

1. Verknüpfen Sie in Partner Center das Partner Center-Konto Ihres Unternehmens mit dem Azure AD-Verzeichnis Ihrer Organisation.

2. Als nächstes fügen Sie auf der Seite Benutzer im Abschnitt Kontoeinstellungen des Partner Centers die Azure AD-Anwendung hinzu, die die Anwendung oder den Dienst repräsentiert, die/den Sie zur Verwaltung von Werbekampagnen für Ihr Partner Center-Konto verwenden werden. Stellen Sie sicher, dass Sie diese Anwendung der rolle Manager zuweisen. Wenn die Anwendung noch nicht in Ihrem Azure AD-Verzeichnis vorhanden ist, können Sie eine neue Azure AD-Anwendung im Partner Centererstellen.

3. Kehren Sie zur Seite Benutzer zurück, klicken Sie auf den Namen Ihrer Azure AD-Anwendung, um zu den Anwendungseinstellungen zu wechseln, und kopieren Sie die werte Mandanten-ID und Client-ID.

4. Klicken Sie auf Neuen Schlüssel hinzufügen. Kopieren Sie auf dem folgenden Bildschirm den Wert Schlüssel. Nachdem Sie diese Seite verlassen haben, können Sie nicht mehr auf diese Informationen zugreifen. Weitere Informationen finden Sie unter Verwalten von Schlüsseln für eine Azure AD-Anwendung.

Schritt 2: Abrufen eines Azure AD-Zugriffstokens

Bevor Sie eine der Methoden in der Microsoft Store-Werbungs-API aufrufen, müssen Sie zuerst ein Azure AD-Zugriffstoken abrufen, das Sie an den header der Authorization jeder Methode in der API übergeben. Nachdem Sie ein Zugriffstoken abgerufen haben, müssen Sie es 60 Minuten verwenden, bevor es abläuft. Nachdem das Token abgelaufen ist, können Sie das Token aktualisieren, damit Sie es weiterhin in weiteren Aufrufen der API verwenden können.

Um das Zugriffstoken abzurufen, befolgen Sie die Anweisungen in Dienstanrufe mithilfe von Clientanmeldeinformationen, um einen HTTP POST an den https://login.microsoftonline.com/<tenant_id>/oauth2/token Endpunkt zu senden. Hier ist eine Beispielanforderung.

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 für den tenant_id Wert im POST-URI und den Parametern client_id und client_secret die Mandanten-ID, die Client-ID und den Schlüssel für Ihre Anwendung an, die Sie im vorherigen Abschnitt aus Partner Center abgerufen haben. Für den parameter Ressource müssen Sie https://manage.devcenter.microsoft.comangeben.

Nachdem Ihr Zugriffstoken abgelaufen ist, können Sie es aktualisieren, indem Sie die Anweisungen hierfolgen.

Schritt 3: Aufrufen der Microsoft Store-Werbungs-API

Nachdem Sie über ein Azure AD-Zugriffstoken verfügen, können Sie die Microsoft Store-Werbungs-API aufrufen. Sie müssen das Zugriffstoken an den Authorization Header jeder Methode übergeben.

Im Zusammenhang mit der Microsoft Store Promotions-API besteht eine Werbekampagne aus einem Kampagnenobjekt , das allgemeine Informationen über die Kampagne enthält, und zusätzlichen Objekten, die die Lieferlinien, Targeting-Profileund Kreative für die Werbekampagne darstellen. Die API enthält verschiedene Gruppen von Methoden, die von diesen Objekttypen gruppiert werden. Zum Erstellen einer Kampagne rufen Sie in der Regel eine andere POST-Methode für jedes dieser Objekte auf. Die API stellt außerdem GET-Methoden bereit, mit der Sie alle Objekte und PUT-Methoden abrufen können, die Sie zum Bearbeiten von Kampagnen-, Lieferzeilen- und Zielprofilobjekten verwenden können.

Weitere Informationen zu diesen Objekten und den zugehörigen Methoden finden Sie in der folgenden Tabelle.

Objekt	Beschreibung
Feldzüge	Dieses Objekt stellt die Anzeigenkampagne dar und befindet sich am Anfang der Objektmodellhierarchie für Anzeigenkampagnen. Dieses Objekt identifiziert die Art der Kampagne, die Sie durchführen (bezahlte, interne oder Gemeinschafts-), das Kampagnenziel, die Auslieferungslinien für die Kampagne und weitere Details. Jede Kampagne kann nur einer App zugeordnet werden. Weitere Informationen zu den Methoden für dieses Objekt finden Sie unter Verwalten von Anzeigenkampagnen. Hinweis Nachdem Sie eine Anzeigenkampagne erstellt haben, können Sie Leistungsdaten für die Kampagne mithilfe der Get Ad Campaign Performance Data Methode in der Microsoft Store-Analyse-APIabrufen.
Lieferlinien	Jede Kampagne verfügt über eine oder mehrere Auslieferungslinien, die genutzt werden, um Inventar einzukaufen und Anzeigen zu liefern. Für jede Lieferposition können Sie die Zielbestimmung festlegen, ihren Angebotspreis festlegen und entscheiden, wie viel Sie ausgeben möchten, indem Sie ein Budget festlegen und eine Verknüpfung mit Kreativen herstellen, die Sie verwenden möchten. Weitere Informationen zu den Methoden, die mit diesem Objekt verbunden sind, finden Sie unter Verwaltung von Lieferlinien für Anzeigenkampagnen.
Zielgruppenprofile	Jede Lieferposition verfügt über ein Zielprofil, das die Benutzer, Regionen und Bestandstypen angibt, auf die Sie abzielen möchten. Zielprofile können als Vorlage erstellt und über Lieferpositionen hinweg freigegeben werden. Weitere Informationen zu den Methoden für dieses Objekt finden Sie unter Verwalten von Zielgruppenprofilen für Anzeigenkampagnen.
Kreative	Jede Lieferlinie hat einen oder mehrere Werbemittel, die die Anzeigen darstellen, die den Kunden im Rahmen der Kampagne angezeigt werden. Ein Creative kann mit einer oder mehreren Lieferzeilen verknüpft sein, auch über Werbekampagnen hinweg, vorausgesetzt, es stellt immer die gleiche App dar. Weitere Informationen zu den Methoden, die mit diesem Objekt zusammenhängen, finden Sie unter Werbemittel für Werbekampagnen verwalten.

Das folgende Diagramm veranschaulicht die Beziehung zwischen Kampagnen, Lieferlinien, Targeting-Profilen und Kreativen.

Codebeispiel

Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein Azure AD-Zugriffstoken abrufen und die Microsoft Store-Werbungs-API aus einer C#-Konsolen-App aufrufen. Um dieses Codebeispiel zu verwenden, weisen Sie die tenantId, clientId, clientSecret-und appID- Variablen den entsprechenden Werten für Ihr Szenario zu. In diesem Beispiel wird das Json.NET-Paket von Newtonsoft benötigt, um die JSON-Daten zu deserialisieren, die von der Microsoft Store-Werbungs-API zurückgegeben werden.

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;
        }
    }
}

Verwandte Themen

• Verwalten von Anzeigenkampagnen
• Verwalten Sie Zustellleitungen für Werbekampagnen
• Verwalten von Zielgruppenprofilen für Anzeigenkampagnen
• Verwaltung von Werbemitteln für Werbekampagnen
• Abrufen von Leistungsdaten für Anzeigenkampagnen