Freigeben über

Ausführen von Anzeigenkampagnen mit Store-Diensten

  • Artikel

Verwenden Sie die Microsoft Store-Werbungs-API , um Werbekampagnen für Apps programmgesteuert zu verwalten, die für Das Partner Center-Konto 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) zum Autorisieren der Aufrufe von Ihrer App oder Ihrem Dienst.

Dazu müssen folgende Schritte ausgeführt werden:

  1. Stellen Sie sicher, dass Sie alle Voraussetzungen erfüllt haben.
  2. Rufen Sie vor dem Aufrufen einer Methode in der Microsoft Store-Werbungs-API ein Azure AD-Zugriffstoken ab. 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. Rufen Sie die Microsoft Store-Werbungs-API auf.

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.

Hinweis

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 Anfrage 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 Seite "Anzeigenkampagnen" im Partner Center erstellen und mindestens ein Zahlungsmittel auf dieser Seite hinzufügen. Anschließend können Sie mithilfe dieser API erfolgreich rechnungsbare Lieferpositionen für Anzeigenkampagnen erstellen. Lieferpositionen für Anzeigenkampagnen, die Sie mit dieser API erstellen, berechnet automatisch das standardzahlungsinstrument, das auf der Seite "Anzeigenkampagnen" im Partner Center ausgewählt wurde.

  • 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. Wenn Sie Microsoft 365 oder andere Unternehmensdienste von Microsoft verwenden, verfügen Sie bereits über ein Azure AD-Verzeichnis. Andernfalls können Sie ohne zusätzliche Kosten eine neue Azure AD-Instanz in Partner Center 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 zu erhalten, das Sie an die API übergeben.

    Hinweis

    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 Ihrer Organisation mit dem Azure AD-Verzeichnis Ihrer Organisation.

  2. Fügen Sie als Nächstes auf der Seite "Benutzer" im Abschnitt "Kontoeinstellungen" des Partner Center die Azure AD-Anwendung hinzu, die die App oder den Dienst darstellt, die Sie zum Verwalten von Werbekampagnen für Ihr Partner Center-Konto verwenden. Stellen Sie sicher, dass Sie dieser Anwendung die Rolle Manager zuweisen. Wenn die Anwendung noch nicht in Ihrem Azure AD-Verzeichnis vorhanden ist, können Sie in Partner Center eine neue Azure AD-Anwendung erstellen.

  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.

  4. Klicken Sie auf Neuen Schlüssel hinzufügen. Notieren Sie auf dem folgenden Bildschirm den Wert von 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 Autorisierungsheader jeder Methode in der API übergeben. Nachdem Sie ein Zugriffstoken erhalten haben, haben Sie 60 Minuten Zeit, es zu verwenden, bevor es abläuft. Nach dem Ablauf können Sie das Token aktualisieren, damit Sie es in weiteren Aufrufen der API weiterhin verwenden können.

Um das Zugriffstoken zu erhalten, folgen Sie den Anweisungen in Aufrufe von Dienst zu Dienst mit Anmeldeinformationen des Clients, 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

Für den Wert Mandant_id im POST-URI und die Parameter Client_id und Client_secret geben Sie die ID des Mandanten, die ID des Clients und den Schlüssel für Ihre Anwendung an, den Sie im vorherigen Abschnitt vom Partner Center erhalten haben. Für den Parameter resource müssen Sie https://manage.devcenter.microsoft.com angeben.

Nachdem Ihr Zugriffstoken abgelaufen ist, können Sie es aktualisieren, indem Sie die anweisungen hier befolgen.

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 Autorisierungsheader jeder Methode übergeben.

Im Kontext der Microsoft Store-Werbungs-API besteht eine Anzeigenkampagne aus einem Kampagnenobjekt , das allgemeine Informationen zur Kampagne sowie zusätzliche Objekte enthält, die die Lieferpositionen, Zielgruppenprofile und Werbemittel für die Anzeigenkampagne 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.

Object Beschreibung
Kampagnen 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 ausführen (kostenpflichtig, haus oder community), das Kampagnenziel, die Lieferpositionen für die Kampagne und andere Details. Jede Kampagne kann nur einer App zugeordnet werden.

Weitere Informationen zu den Methoden im Zusammenhang mit diesem Objekt finden Sie unter Verwalten von Anzeigenkampagnen.

Hinweis : Nachdem Sie eine Anzeigenkampagne erstellt haben, können Sie Leistungsdaten für die Kampagne abrufen, indem Sie die Datenmethode zum Abrufen von Leistungsdaten für Anzeigenkampagnen in der Microsoft Store-Analyse-API verwenden.
Lieferpositionen Jede Kampagne verfügt über eine oder mehrere Lieferpositionen, die verwendet werden, um Lagerbestände zu kaufen und Ihre 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 für dieses Objekt finden Sie unter Verwalten von Lieferpositionen für Anzeigenkampagnen.
Zielprofile 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 Lieferposition verfügt über einen oder mehrere Werbemittel, die die Anzeigen darstellen, die Kunden als Teil der Kampagne angezeigt werden. Ein Werbemittel kann einer oder mehreren Lieferpositionen zugeordnet werden, auch über Anzeigenkampagnen hinweg, vorausgesetzt, sie stellt immer dieselbe App dar.

Weitere Informationen zu den Methoden für dieses Objekt finden Sie unter Verwalten von Werbemittel für Anzeigenkampagnen.

Das folgende Diagramm veranschaulicht die Beziehung zwischen Kampagnen, Lieferpositionen, Zielgruppenprofilen und Werbemittel.

Hierarchie der Anzeigenkampagne

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 Variablen "tenantId", "clientId", "clientSecret" und "appID " 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;
        }
    }
}