스토어 서비스를 사용 하 여 ad 캠페인 실행Run ad campaigns using Store services

Microsoft Store 프로 모션 API 를 사용 하 여 또는 조직의 파트너 센터 계정에 등록 된 앱에 대 한 프로 모션 광고 캠페인을 프로그래밍 방식으로 관리 합니다.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. 이 API를 사용 하 여 캠페인을 만들고, 업데이트 하 고, 대상 및 creatives 등의 기타 관련 자산을 모니터링할 수 있습니다.This API enables you to create, update and monitor your campaigns and other related assets such as targeting and creatives. 이 API는 특히 파트너 센터를 사용 하지 않고 많은 양의 캠페인을 만드는 개발자에 게 유용 합니다.This API is especially useful for developers who create large volumes of campaigns, and who want to do so without using Partner Center. 이 API는 Azure Active Directory (Azure AD)를 사용 하 여 앱 또는 서비스에서 호출을 인증 합니다.This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

다음 단계는 종단 간 프로세스를 설명 합니다.The following steps describe the end-to-end process:

  1. 모든 필수 구성 요소를 완료 했는지 확인 합니다.Make sure that you have completed all the prerequisites.
  2. Microsoft Store 프로 모션 API에서 메서드를 호출 하기 전에 AZURE AD 액세스 토큰을 가져옵니다.Before you call a method in the Microsoft Store promotions API, obtain an Azure AD access token. 토큰을 가져온 후에는 토큰이 만료 되기 전에 Microsoft Store 프로 모션 API에 대 한 호출에서이 토큰을 사용 하는 데 60 분이 소요 됩니다.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. 토큰이 만료 된 후 새 토큰을 생성할 수 있습니다.After the token expires, you can generate a new token.
  3. Microsoft Store 프로 모션 API를 호출합니다.Call the Microsoft Store promotions API.

또는 파트너 센터를 사용 하 여 ad 캠페인을 만들고 관리할 수 있으며, Microsoft Store 프로 모션 API를 통해 프로그래밍 방식으로 만드는 모든 ad 캠페인은 파트너 센터 에서도 액세스할 수 있습니다.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. 파트너 센터에서 ad 캠페인을 관리 하는 방법에 대 한 자세한 내용은 앱에 대 한 광고 캠페인 만들기를 참조 하세요.For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

참고

파트너 센터 계정이 있는 개발자는 Microsoft Store 프로 모션 API를 사용 하 여 앱에 대 한 광고 캠페인을 관리할 수 있습니다.Any developer with a Partner Center account can use the Microsoft Store promotions API to manage ad campaigns for their apps. 또한 미디어 기관은이 API에 대 한 액세스를 요청 하 여 광고주를 대신 하 여 ad 캠페인을 실행할 수 있습니다.Media agencies can also request access to this API to run ad campaigns on behalf of their advertisers. 이 API에 대 한 자세한 정보를 알고자 하거나 액세스를 요청 하는 미디어 에이전시 인 경우에 요청을 보냅니다 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.

1 단계: Microsoft Store 프로 모션 API를 사용 하기 위한 필수 구성 요소 완료Step 1: Complete prerequisites for using the Microsoft Store promotions API

Microsoft Store 프로 모션 API를 호출 하는 코드 작성을 시작 하기 전에 다음 필수 구성 요소를 완료 했는지 확인 합니다.Before you start writing code to call the Microsoft Store promotions API, make sure that you have completed the following prerequisites.

  • 이 API를 사용 하 여 ad 캠페인을 성공적으로 만들고 시작 하려면 먼저 파트너 센터의 ad 캠페인 페이지를 사용 하 여 유료 ad 캠페인을 만들고이 페이지에서 결제 방법을 하나 이상 추가 해야 합니다.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. 이 작업을 수행한 후에는이 API를 사용 하 여 광고 캠페인에 대해 청구 가능한 배달 줄을 성공적으로 만들 수 있습니다.After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. 이 API를 사용 하 여 만든 ad 캠페인의 배달 줄은 파트너 센터의 ad 캠페인 페이지에서 선택한 기본 결제 방법을 자동으로 청구 합니다.Delivery 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.

  • 사용자(또는 조직)는 Azure AD 디렉터리가 있어야 하고 디렉터리에 대한 전역 관리자 권한이 있어야 합니다.You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. Microsoft에서 이미 Microsoft 365 또는 다른 비즈니스 서비스를 사용 하는 경우 Azure AD 디렉터리가 이미 있습니다.If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory. 그렇지 않으면 추가 비용 없이 파트너 센터에서 새 AZURE AD를 만들 수 있습니다.Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • Azure AD 응용 프로그램을 파트너 센터 계정에 연결 하 고, 응용 프로그램에 대 한 테 넌 트 ID와 클라이언트 ID를 검색 하 고, 키를 생성 해야 합니다.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. Azure AD 응용 프로그램은 Microsoft Store 프로 모션 API를 호출 하려는 응용 프로그램 또는 서비스를 나타냅니다.The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. API에 전달하는 Azure AD 액세스 토큰을 얻으려면 테넌트 ID, 클라이언트 ID 및 키가 필요합니다.You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    참고

    이 작업은 한 번만 수행 하면 됩니다.You only need to perform this task one time. 테넌트 ID, 클라이언트 ID 및 키가 있으면 새 Azure AD 액세스 토큰을 만들어야 할 때마다 다시 사용할 수 있습니다.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.

Azure AD 응용 프로그램을 파트너 센터 계정에 연결 하 고 필요한 값을 검색 하려면 다음을 수행 합니다.To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. 파트너 센터에서 조직의 파트너 센터 계정을 조직의 Azure AD 디렉터리에 연결합니다.In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. 그런 다음 파트너 센터의 계정 설정 섹션에 있는 사용자 페이지에서 파트너 센터 계정에 대 한 프로 모션 캠페인을 관리 하는 데 사용할 앱 또는 서비스를 나타내는 Azure AD 응용 프로그램을 추가 합니다.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. 이 애플리케이션을 관리자 역할에 할당해야 합니다.Make sure you assign this application the Manager role. 애플리케이션이 아직 Azure AD 디렉터리에 존재하지 않는 경우 파트너 센터에서 새 Azure AD 애플리케이션 만들 수 있습니다.If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. 사용자 페이지로 돌아가 Azure AD 애플리케이션의 이름을 클릭하여 애플리케이션 설정으로 이동한 다음 테넌트 ID클라이언트 ID 값을 복사합니다.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. 새 키 추가를 클릭합니다.Click Add new key. 다음 화면에서 값을 복사합니다.On the following screen, copy down the Key value. 이 페이지를 나가면 이 정보에 다시 액세스할 수 없습니다.You won't be able to access this info again after you leave this page. 자세한 내용은 Azure AD 애플리케이션 키 관리를 참조하세요.For more information, see Manage keys for an Azure AD application.

2단계: Azure AD 액세스 토큰 가져오기Step 2: Obtain an Azure AD access token

Microsoft Store 프로 모션 API에서 메서드를 호출 하기 전에 먼저 API의 각 메서드에 대 한 인증 헤더에 전달 하는 Azure AD 액세스 토큰을 가져와야 합니다.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. 액세스 토큰을 얻은 후 만료되기 전에 60분 동안 사용할 수 있습니다.After you obtain an access token, you have 60 minutes to use it before it expires. 토큰이 만료 된 후에는 API에 대 한 추가 호출에서 토큰을 계속 사용할 수 있도록 토큰을 새로 고칠 수 있습니다.After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

액세스 토큰을 가져오려면 클라이언트 자격 증명을 사용 하 여 서비스 호출 에 대 한 지침에 따라 HTTP POST를 끝점으로 보냅니다 https://login.microsoftonline.com/<tenant_id>/oauth2/token .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. 샘플 요청은 다음과 같습니다.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

POST URI와 클라이언트 * _ id* 및 클라이언트 _ 암호 매개 변수의 테 넌 트 _ Id 값에 대해 이전 섹션의 파트너 센터에서 검색 한 응용 프로그램의 테 넌 트 id, 클라이언트 id 및 키를 지정 합니다.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. 리소스 매개 변수에는 https://manage.devcenter.microsoft.com을 지정해야 합니다.For the resource parameter, you must specify https://manage.devcenter.microsoft.com.

액세스 토큰이 만료 되 면 여기에 설명 된 지침에 따라 새로 고칠 수 있습니다.After your access token expires, you can refresh it by following the instructions here.

3 단계: Microsoft Store 프로 모션 API 호출Step 3: Call the Microsoft Store promotions API

Azure AD 액세스 토큰이 있으면 Microsoft Store 프로 모션 API를 호출할 준비가 된 것입니다.After you have an Azure AD access token, you are ready to call the Microsoft Store promotions API. 각 메서드의 인증 헤더에 액세스 토큰을 전달 해야 합니다.You must pass the access token to the Authorization header of each method.

Microsoft Store 프로 모션 API의 컨텍스트에서 ad 캠페인은 캠페인에 대 한 개략적인 정보를 포함 하는 캠페인 개체와, 광고 캠페인에 대 한 배달 선, 대상 프로필creatives 를 나타내는 추가 개체를 구성 합니다.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. API에는 이러한 개체 형식으로 그룹화 되는 다양 한 메서드 집합이 포함 되어 있습니다.The API includes different sets of methods that are grouped by these object types. 캠페인을 만들려면 일반적으로 이러한 각 개체에 대해 다른 POST 메서드를 호출 합니다.To create a campaign, you typically call a different POST method for each of these objects. 또한 API는 캠페인, 배달 선 및 대상 프로필 개체를 편집 하는 데 사용할 수 있는 개체 및 PUT 메서드를 검색 하는 데 사용할 수 있는 GET 메서드를 제공 합니다.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.

이러한 개체 및 관련 메서드에 대 한 자세한 내용은 다음 표를 참조 하십시오.For more information about these objects and their related methods, see the following table.

ObjectObject 설명Description
캠페인Campaigns 이 개체는 ad 캠페인을 나타내며, 광고 캠페인의 개체 모델 계층 구조 맨 위에 있습니다.This object represents the ad campaign, and it sits at the top of the object model hierarchy for ad campaigns. 이 개체는 실행 중인 캠페인 유형 (유료, 집 또는 커뮤니티), 캠페인 목표, 캠페인의 배달 선 및 기타 세부 정보를 식별 합니다.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. 각 캠페인은 하나의 앱에만 연결할 수 있습니다.Each campaign can be associated with only one app.

이 개체와 관련 된 메서드에 대 한 자세한 내용은 ad 캠페인 관리를 참조 하세요.For more information about the methods related to this object, see Manage ad campaigns.

Note   참고   광고 캠페인을 만든 후 Microsoft Store 분석 API에서 ad 캠페인 성능 데이터 가져오기 방법을 사용 하 여 캠페인에 대 한 성능 데이터를 검색할 수 있습니다.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.
배달 라인Delivery lines 모든 캠페인에는 재고를 구입 하 고 광고를 배달 하는 데 사용 되는 하나 이상의 배달 회선이 있습니다.Every campaign has one or more delivery lines that are used to buy inventory and deliver your ads. 각 배달 라인에 대해 대상을 설정 하 고, 입찰 가격을 설정 하 고, 사용 하려는 creatives에 대 한 예산 및 링크를 설정 하 여 비용을 결정 하는 데 사용할 수 있습니다.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.

이 개체와 관련 된 메서드에 대 한 자세한 내용은 ad 캠페인의 배달 선 관리를 참조 하세요.For more information about the methods related to this object, see Manage delivery lines for ad campaigns.
대상 프로필Targeting profiles 모든 배달 라인에는 대상으로 지정할 사용자, 지역 및 재고 유형을 지정 하는 대상 프로필이 하나 있습니다.Every delivery line has one targeting profile that specifies the users, geographies and inventory types that you want to target. 대상 프로필을 템플릿으로 만들고 배달 줄에서 공유할 수 있습니다.Targeting profiles can be created as a template and shared across delivery lines.

이 개체와 관련 된 메서드에 대 한 자세한 내용은 ad 캠페인의 대상 프로필 관리를 참조 하세요.For more information about the methods related to this object, see Manage targeting profiles for ad campaigns.
CreativesCreatives 모든 배달 라인에는 캠페인의 일부로 고객에 게 표시 되는 광고를 나타내는 하나 이상의 creatives 있습니다.Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. Creative는 항상 동일한 앱을 나타내는 ad 캠페인을 통해 하나 이상의 배달 선과 연결 될 수 있습니다.A creative may be associated with one or more delivery lines, even across ad campaigns, provided it always represents the same app.

이 개체와 관련 된 메서드에 대 한 자세한 내용은 Manage creatives for ad 캠페인과항목을 참조 하세요.For more information about the methods related to this object, see Manage creatives for ad campaigns.

다음 다이어그램은 캠페인, 배달 선, 대상 프로필 및 creatives 간의 관계를 보여 줍니다.The following diagram illustrates the relationship between campaigns, delivery lines, targeting profiles, and creatives.

Ad 캠페인 계층 구조

코드 예제Code example

다음 코드 예제에서는 Azure AD 액세스 토큰을 가져오고 c # 콘솔 앱에서 Microsoft Store 프로 모션 API를 호출 하는 방법을 보여 줍니다.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. 이 코드 예제를 사용 하려면 사용자의 시나리오에 맞게 tenantId, clientId, clientSecretappID 변수를 적절 한 값에 할당 합니다.To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. 이 예에서는 Newtonsoft.json의 Json.NET 패키지가 Microsoft Store 프로 모션 API에서 반환 된 Json 데이터를 deserialize 해야 합니다.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;
        }
    }
}