Uruchamianie kampanii reklamowych przy użyciu usług Sklepu

Użyj interfejsu API promocji sklepu Microsoft Store, aby zarządzać programowo kampaniami promocyjnymi reklamowymi dla aplikacji zarejestrowanych na koncie Centrum Partnerskiego Ciebie lub Twojej organizacji. Ten interfejs API umożliwia tworzenie, aktualizowanie i monitorowanie kampanii oraz innych powiązanych zasobów, takich jak kierowanie i kreacje. Ten interfejs API jest szczególnie przydatny dla deweloperów, którzy tworzą duże ilości kampanii i chcą to zrobić bez korzystania z Centrum partnerskiego. Ten interfejs API używa usługi Azure Active Directory (Azure AD) do uwierzytelniania wywołań z aplikacji lub usługi.

W poniższych krokach opisano pełny proces:

1. Upewnij się, że zostały spełnione wszystkie wymagania wstępne .
2. Przed wywołaniem metody w interfejsie API promocji sklepu Microsoft Store uzyskaj token dostępu usługi Azure AD. Po uzyskaniu tokenu należy 60 minut używać tego tokenu w wywołaniach do interfejsu API promocji sklepu Microsoft Store przed wygaśnięciem tokenu. Po wygaśnięciu tokenu możesz wygenerować nowy token.
3. Wywołaj interfejs API promocji sklepu Microsoft Store.

Możesz też tworzyć kampanie reklamowe i zarządzać nimi przy użyciu Centrum partnerskiego, a wszelkie kampanie reklamowe tworzone programowo za pośrednictwem interfejsu API promocji sklepu Microsoft Store również można uzyskać w Centrum partnerskim. Aby uzyskać więcej informacji na temat zarządzania kampaniami reklamowymi w Centrum partnerskim, zobacz Tworzenie kampanii reklamowej dla aplikacji.

Krok 1. Pełne wymagania wstępne dotyczące korzystania z interfejsu API promocji w sklepie Microsoft Store

Przed rozpoczęciem pisania kodu w celu wywołania interfejsu API promocji sklepu Microsoft Store upewnij się, że zostały spełnione następujące wymagania wstępne.

• Przed pomyślnym utworzeniem i rozpoczęciem kampanii reklamowej przy użyciu tego interfejsu API należy najpierw utworzyć jedną płatną kampanię reklamową przy użyciu strony kampanii reklamowych w Centrum partnerskim, a na tej stronie musisz dodać co najmniej jeden instrument płatniczy. Po wykonaniu tej czynności będzie można pomyślnie utworzyć rozliczane linie dostarczania dla kampanii reklamowych przy użyciu tego interfejsu API. Linie dostarczania dla kampanii reklamowych tworzonych przy użyciu tego interfejsu API będą automatycznie rozliczać domyślny instrument płatniczy wybrany na stronie kampanii reklamowych w Centrum partnerskim.

• Użytkownik (lub twoja organizacja) musi mieć katalog usługi Azure AD i musisz mieć uprawnienia administratora globalnego dla katalogu. Jeśli korzystasz już z platformy Microsoft 365 lub innych usług biznesowych, masz już katalog usługi Azure AD. W przeciwnym razie możesz utworzyć nową usługę Azure AD w Centrum partnerskim bez dodatkowych opłat.

• Musisz skojarzyć aplikację usługi Azure AD z kontem Centrum partnerskiego, pobrać identyfikator dzierżawy i identyfikator klienta dla aplikacji i wygenerować klucz. Aplikacja usługi Azure AD reprezentuje aplikację lub usługę, z której chcesz wywołać interfejs API promocji sklepu Microsoft Store. Potrzebujesz identyfikatora dzierżawy, identyfikatora klienta i klucza, aby uzyskać token dostępu Azure AD, który przekażesz do interfejsu API.

  Notatka

  To zadanie trzeba wykonać tylko raz. Po utworzeniu identyfikatora dzierżawy, identyfikatora klienta i klucza możesz użyć ich ponownie w dowolnym momencie, gdy musisz utworzyć nowy token dostępu usługi Azure AD.

Aby skojarzyć aplikację usługi Azure AD z kontem Centrum partnerskiego i pobrać wymagane wartości:

1. W Centrum Partnerów skojarz konto Centrum Partnerów Twojej organizacji z katalogiem Azure AD Twojej organizacji.

2. Następnie, na stronie Użytkownicy w sekcji ustawienia konta Centrum partnerskiego, dodaj aplikację Azure AD, która reprezentuje aplikację lub usługę, której będziesz używać do zarządzania kampaniami promocyjnymi dla konta w Centrum partnerskim. Upewnij się, że przypiszesz tej aplikacji rolę menedżera. Jeśli aplikacja jeszcze nie istnieje w katalogu usługi Azure AD, możesz utworzyć nową aplikację usługi Azure AD w Centrum partnerskim.

3. Wróć do strony Użytkownicy, kliknij nazwę aplikacji usługi Azure AD, aby przejść do ustawień aplikacji, a następnie skopiuj wartości identyfikatora dzierżawy i identyfikator klienta.

4. Kliknij pozycję Dodaj nowy klucz. Na poniższym ekranie skopiuj wartość Klucz . Po opuszczeniu tej strony nie będzie można ponownie uzyskać dostępu do tych informacji. Aby uzyskać więcej informacji, zobacz Zarządzanie kluczami dla aplikacji usługi Azure AD.

Krok 2. Uzyskiwanie tokenu dostępu usługi Azure AD

Przed wywołaniem dowolnej metody w API promocji Microsoft Store należy najpierw uzyskać token dostępu Azure AD, który należy przekazać do nagłówka autoryzacji Authorization każdej metody w API. Po uzyskaniu tokenu dostępu należy 60 minut używać go przed jego wygaśnięciem. Po wygaśnięciu tokenu możesz odświeżyć token, aby móc nadal używać go w kolejnych wywołaniach interfejsu API.

Aby uzyskać token dostępu, postępuj zgodnie z instrukcjami w Service to Service Calls Using Client Credentials (Wywołania usługi do usługi przy użyciu poświadczeń klienta) i wyślij żądanie HTTP POST do punktu końcowego https://login.microsoftonline.com/<tenant_id>/oauth2/token. Oto przykładowe żądanie.

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

Dla parametru tenant_id w identyfikatorze URI POST oraz parametrów client_id i client_secret określ identyfikator dzierżawy, identyfikator klienta i klucz dla aplikacji, który pobrałeś z Centrum Partnerów w poprzedniej sekcji. Dla parametru zasobu należy określić https://manage.devcenter.microsoft.com.

Po wygaśnięciu tokenu dostępu możesz go odświeżyć, postępując zgodnie z instrukcjami tutaj.

Krok 3: Wywoływanie interfejsu API promocji sklepu Microsoft Store

Po uzyskaniu tokenu dostępu usługi Azure AD możesz wywołać interfejs API do promocji sklepu Microsoft Store. Należy przekazać token dostępu do nagłówka autoryzacji każdej metody.

W kontekście interfejsu API promocji sklepu Microsoft Store kampania reklamowa składa się z obiektu kampanii , który zawiera ogólne informacje o kampanii, oraz dodatkowych obiektów reprezentujących linie emisji , profile docelowe , i kreacje kampanii reklamowej. Interfejs API zawiera różne zestawy metod pogrupowanych według tych typów obiektów. Aby utworzyć kampanię, zazwyczaj wywołujesz inną metodę POST dla każdego z tych obiektów. Interfejs API udostępnia również metody GET, których można użyć do pobrania dowolnego obiektu, oraz metody PUT, których można użyć do edytowania obiektów kampanii, linii przesyłki i profilów celowania.

Aby uzyskać więcej informacji o tych obiektach i ich powiązanych metodach, zobacz poniższą tabelę.

Na poniższym diagramie przedstawiono relację między kampaniami, liniami dostarczania, profilami określania wartości docelowych i twórcami.

Przykład kodu

W poniższym przykładzie kodu pokazano, jak uzyskać token dostępu usługi Azure AD i wywołać interfejs API promocji sklepu Microsoft Store z poziomu aplikacji konsolowej języka C#. Aby użyć tego przykładu kodu, przypisz tenantId, clientId, clientSecreti appID zmiennych do odpowiednich wartości dla danego scenariusza. Ten przykład wymaga pakietu Json.NET firmy Newtonsoft w celu deserializacji danych JSON zwracanych przez interfejs API promocji sklepu Microsoft Store.

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

Tematy pokrewne

• zarządzanie kampaniami reklamowymi
• Zarządzanie liniami dostarczania kampanii reklamowych
• Zarządzanie profilami docelowymi dla kampanii reklamowych
• Zarządzanie kreatywnymi kampaniami reklamowymi
• Uzyskaj dane dotyczące wydajności kampanii reklamowej