Ausführen von Anzeigenkampagnen mithilfe von Store-Diensten
Verwenden Sie die Microsoft Store-Werbe-API, um Werbekampagnen für Apps programmgesteuert zu verwalten, die für Ihr Partner Center-Konto oder das Partner Center-Konto Ihres organization registriert sind. Mit dieser API können Sie Ihre Kampagnen und andere verwandte Ressourcen wie Targeting und Creatives erstellen, aktualisieren und überwachen. Diese API ist besonders nützlich für Entwickler, die große Mengen von Kampagnen erstellen und dies ohne Partner Center tun möchten. Diese API verwendet Azure Active Directory (Azure AD), um die Aufrufe von Ihrer App oder Ihrem Dienst zu authentifizieren.
Dazu müssen folgende Schritte ausgeführt werden:
- Stellen Sie sicher, dass Sie alle Voraussetzungen erfüllt haben.
- Bevor Sie eine Methode in der Microsoft Store-Promotions-API aufrufen, rufen Sie ein Azure AD-Zugriffstoken ab. Nachdem Sie ein Token abgerufen haben, haben Sie 60 Minuten Zeit, dieses Token in Aufrufen der Microsoft Store-Promotions-API zu verwenden, bevor das Token abläuft. Nach dem Ablauf des Tokens können Sie ein neues Token generieren.
- Rufen Sie die Microsoft Store-Promotions-API auf.
Alternativ können Sie Anzeigenkampagnen mit Partner Center erstellen und verwalten, und alle Anzeigenkampagnen, die Sie programmgesteuert über die Microsoft Store-Promotions-API erstellen, können auch im Partner Center zugegriffen werden. Weitere Informationen zum Verwalten von Anzeigenkampagnen in Partner Center finden Sie unter Erstellen einer Anzeigenkampagne für Ihre App.
Hinweis
Jeder Entwickler mit einem Partner Center-Konto kann die Microsoft Store-Werbe-API verwenden, um Anzeigenkampagnen für seine Apps zu verwalten. Medienagenturen können auch Zugriff auf diese API anfordern, um Anzeigenkampagnen im Namen ihrer Werbekunden durchzuführen. Wenn Sie eine Medienagentur sind, die mehr über diese API erfahren oder 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-Promotions-API
Bevor Sie mit dem Schreiben von Code zum Aufrufen der Microsoft Store-Promotions-API beginnen, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllt haben.
Bevor Sie mit dieser API erfolgreich eine Anzeigenkampagne erstellen und starten können, müssen Sie zunächst eine kostenpflichtige Anzeigenkampagne über die Seite Anzeigenkampagnen im Partner Center erstellen und mindestens ein Zahlungsinstrument auf dieser Seite hinzufügen. Danach können Sie mithilfe dieser API erfolgreich abrechenbare Lieferpositionen für Anzeigenkampagnen erstellen. Übermittlungspositionen für Anzeigenkampagnen, die Sie mit dieser API erstellen, werden automatisch das auf der Seite Anzeigenkampagnen im Partner Center ausgewählte Standardzahlungsinstrument in Rechnung gestellt.
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 im Partner Center eine neue Azure AD-Instanz ohne zusätzliche Kosten erstellen.
Sie müssen Ihrem Partner Center-Konto eine Azure AD-Anwendung zuordnen, die Mandanten-ID und client-ID für die Anwendung abrufen und einen Schlüssel generieren. Die Azure AD-Anwendung stellt die App oder den Dienst dar, von der aus Sie die Microsoft Store-Promotions-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 Ihrem Partner Center-Konto eine Azure AD-Anwendung zu und rufen die erforderlichen Werte ab:
Verknüpfen Sie in Partner Center das Partner Center-Konto Ihres Unternehmens mit dem Azure AD-Verzeichnis Ihrer Organisation.
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. 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.
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.
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-Promotions-API aufrufen, müssen Sie zunächst 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. Nachdem das Token abgelaufen ist, können Sie es aktualisieren, um es in weiteren Aufrufen an die API zu verwenden.
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. Hier ist ein Beispiel für eine Anforderung angegeben.
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 wert tenant_id 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 resource müssen Sie https://manage.devcenter.microsoft.com angeben.
Nachdem das Zugriffstoken abgelaufen ist, können Sie es aktualisieren, indem Sie diese Anleitung befolgen.
Schritt 3: Aufrufen der Microsoft Store-Promotions-API
Nachdem Sie über ein Azure AD-Zugriffstoken verfügen, können Sie die Microsoft Store-Promotions-API aufrufen. Sie müssen das Zugriffstoken an den Authorization-Header der einzelnen Methoden übergeben.
Im Kontext der Microsoft Store-Promotions-API besteht eine Anzeigenkampagne aus einem Kampagnenobjekt , das allgemeine Informationen zur Kampagne enthält, sowie aus zusätzlichen Objekten, die die Übermittlungslinien, Targetingprofile und Werbemittel für die Anzeigenkampagne darstellen. Die API enthält verschiedene Methodensätze, die nach diesen Objekttypen gruppiert sind. Zum Erstellen einer Kampagne rufen Sie in der Regel eine andere POST-Methode für jedes dieser Objekte auf. Die API stellt auch GET-Methoden bereit, mit deren Hilfe Sie alle Objekt- und PUT-Methoden abrufen können, die Sie zum Bearbeiten von Kampagnen-, Übermittlungszeilen- 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 oben in der Objektmodellhierarchie für Anzeigenkampagnen. Dieses Objekt identifiziert den Typ der Kampagne, die Sie ausführen (kostenpflichtig, haus- oder community), das Kampagnenziel, die Lieferlinien 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 mithilfe der Get Ad Campaign Performance Data-Methode in der Microsoft Store-Analyse-API abrufen. |
| Lieferlinien | Jede Kampagne verfügt über eine oder mehrere Lieferlinien, die verwendet werden, um Inventar zu kaufen und Ihre Anzeigen zu liefern. Für jede Lieferposition können Sie die Zielgruppenadressierung festlegen, Ihren Gebotspreis 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 im Zusammenhang mit diesem Objekt finden Sie unter Verwalten von Lieferpositionen für Anzeigenkampagnen. |
| Zielgruppenprofile | Jede Übermittlungszeile verfügt über ein Zielprofil, das die Benutzer, geografischen Regionen und Bestandstypen angibt, die Sie als Ziel verwenden möchten. Zielprofile können als Vorlage erstellt und über Übermittlungslinien hinweg freigegeben werden. Weitere Informationen zu den Methoden im Zusammenhang mit diesem Objekt finden Sie unter Verwalten von Zielgruppenprofilen für Anzeigenkampagnen. |
| Kreativen | Jede Lieferlinie verfügt über einen oder mehrere Kreative, die die Anzeigen darstellen, die kunden im Rahmen der Kampagne angezeigt werden. Ein Creative kann einer oder mehreren Lieferlinien zugeordnet sein, auch über Anzeigenkampagnen hinweg, sofern es immer die gleiche App darstellt. Weitere Informationen zu den Methoden im Zusammenhang mit diesem Objekt finden Sie unter Verwalten von Werbemittel für Anzeigenkampagnen. |
Das folgende Diagramm veranschaulicht die Beziehung zwischen Kampagnen, Lieferlinien, Zielprofilen und Kreativen.
Codebeispiel
Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein Azure AD-Zugriffstoken abrufen und die Microsoft Store-Promotions-API aus einer C#-Konsolen-App aufrufen. Wenn Sie dieses Codebeispiel verwenden möchten, weisen Sie die Variablen TenantId, ClientId, ClientSecret und AppID den entsprechenden Werten für Ihr Szenario zu. In diesem Beispiel muss das Json.NET-Paket von Newtonsoft die json-Daten deserialisieren, die von der Microsoft Store-Promotions-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;
}
}
}
Zugehörige Themen
- Verwalten von Anzeigenkampagnen
- Verwalten von Lieferpositionen für Anzeigenkampagnen
- Verwalten von Zielgruppenprofilen für Anzeigenkampagnen
- Verwalten von Werbemittel für Anzeigenkampagnen
- Abrufen der Leistungsdaten einer Anzeigenkampagne
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für