Eseguire campagne pubblicitarie usando i servizi di archiviazioneRun ad campaigns using Store services

Usare l' API delle promozioni Microsoft Store per gestire a livello di codice campagne pubblicitarie promozionali per le app registrate per l'account del centro per i partner o per l'organizzazione.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. Questa API consente di creare, aggiornare e monitorare le campagne e altre risorse correlate, ad esempio la destinazione e le creatività.This API enables you to create, update and monitor your campaigns and other related assets such as targeting and creatives. Questa API è particolarmente utile per gli sviluppatori che creano grandi volumi di campagne e che vogliono farlo senza usare il centro per i partner.This API is especially useful for developers who create large volumes of campaigns, and who want to do so without using Partner Center. Questa API usa Azure Active Directory (Azure AD) per autenticare le chiamate dalla tua app o dal tuo servizio.This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

I passaggi seguenti descrivono l'intero processo:The following steps describe the end-to-end process:

  1. Assicurati di avere completato tutti i prerequisiti.Make sure that you have completed all the prerequisites.
  2. Prima di chiamare un metodo nell'API delle promozioni Microsoft Store, ottenere un token di accesso Azure ad.Before you call a method in the Microsoft Store promotions API, obtain an Azure AD access token. Dopo aver ottenuto un token, sono disponibili 60 minuti per l'uso di questo token nelle chiamate all'API di innalzamento di Microsoft Store prima della scadenza del token.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. Dopo la scadenza del token, puoi generare un nuovo token.After the token expires, you can generate a new token.
  3. Chiamare l'API delle promozioni Microsoft Store.Call the Microsoft Store promotions API.

In alternativa, è possibile creare e gestire campagne pubblicitarie usando il centro per i partner e qualsiasi campagna pubblicitaria creata a livello di codice tramite l'API di promozione Microsoft Store è accessibile anche nel centro per i partner.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. Per altre informazioni sulla gestione delle campagne di Active Directory nel centro per i partner, vedere creare una campagna pubblicitaria per l'app.For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.

Nota

Qualsiasi sviluppatore con un account del centro per i partner può usare l'API delle promozioni Microsoft Store per gestire le campagne ad per le proprie app.Any developer with a Partner Center account can use the Microsoft Store promotions API to manage ad campaigns for their apps. I media agency possono anche richiedere l'accesso a questa API per eseguire campagne pubblicitarie per conto degli inserzionisti.Media agencies can also request access to this API to run ad campaigns on behalf of their advertisers. Se si è un ufficio multimediale che vuole saperne di più su questa API o richiedere l'accesso, inviare la richiesta a 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.

Passaggio 1: completare i prerequisiti per l'uso dell'API Microsoft Store PromotionsStep 1: Complete prerequisites for using the Microsoft Store promotions API

Prima di iniziare a scrivere il codice per chiamare l'API delle promozioni Microsoft Store, assicurarsi di aver completato i prerequisiti seguenti.Before you start writing code to call the Microsoft Store promotions API, make sure that you have completed the following prerequisites.

  • Prima di poter creare e avviare una campagna di Active Directory usando questa API, è necessario creare prima una campagna ad a pagamento usando la pagina delle campagne pubblicitarie nel centro per i partnered è necessario aggiungere almeno uno strumento di pagamento in questa pagina.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. Al termine di questa operazione, sarà possibile creare correttamente linee di consegna fatturabili per le campagne pubblicitarie usando questa API.After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. Le linee di recapito per le campagne pubblicitarie create tramite questa API fatturano automaticamente lo strumento di pagamento predefinito scelto nella pagina campagne pubblicitarie del centro per i partner.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.

  • L'utente o l'organizzazione deve disporre di una directory di Azure AD e dell'autorizzazione come amministratore aziendale per la directory.You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. Se si usa già Microsoft 365 o altri servizi aziendali di Microsoft, è già presente Azure AD directory.If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory. In caso contrario, è possibile creare un nuovo Azure ad nel centro per i partner senza costi aggiuntivi.Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • È necessario associare un'applicazione Azure AD all'account del centro per i partner, recuperare l'ID del tenant e l'ID client per l'applicazione e generare una chiave.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. L'applicazione Azure AD rappresenta l'app o il servizio da cui si vuole chiamare l'API di promozione Microsoft Store.The Azure AD application represents the app or service from which you want to call the Microsoft Store promotions API. Per ottenere un token di accesso di Azure AD da passare all'API, sono necessari l'ID tenant, l'ID client e la chiave.You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    Nota

    È sufficiente eseguire questa attività una sola volta.You only need to perform this task one time. Quando si dispone di ID tenant, ID client e chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso 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.

Per associare un'applicazione Azure AD all'account del centro per i partner e recuperare i valori richiesti:To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. Nel Centro per i partner, associare l'account del Centro per i partner dell'organizzazione alla directory di Azure AD dell'organizzazione.In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. Quindi, dalla pagina utenti nella sezione Impostazioni account del centro per i partner, aggiungere l'applicazione Azure ad che rappresenta l'app o il servizio che verrà usato per gestire le campagne di promozione per l'account del centro per i partner.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. Assicurarsi di assegnare a questa applicazione il ruolo di Manager.Make sure you assign this application the Manager role. Se l'applicazione non esiste ancora nella directory di Azure AD, è possibile creare una nuova applicazione Azure AD nel Centro per i partner.If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. Tornare alla pagina Utenti, fare clic sul nome dell'applicazione Azure AD per passare alle impostazioni e copiare i valori di ID tenant e ID client.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. Fare clic su Aggiungi nuova chiave.Click Add new key. Nella schermata seguente, copiare il valore della chiave.On the following screen, copy down the Key value. Non sarà più possibile accedere a queste informazioni dopo aver lasciato la pagina.You won't be able to access this info again after you leave this page. Per altre informazioni, vedere Gestire le chiavi per un'applicazione Azure AD.For more information, see Manage keys for an Azure AD application.

Passaggio 2: Ottenere un token di accesso di Azure ADStep 2: Obtain an Azure AD access token

Prima di chiamare uno dei metodi nell'API Microsoft Store Promotions, è prima necessario ottenere un token di accesso Azure AD passato all'intestazione di autorizzazione di ogni metodo nell'API.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. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza.After you obtain an access token, you have 60 minutes to use it before it expires. Una volta scaduto il token, puoi aggiornarlo in modo da continuare a usarlo in altre chiamate all'API.After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

Per ottenere il token di accesso, segui le istruzioni in Chiamate da servizio a servizio tramite le credenziali del client per inviare un comando POST HTTP all'endpoint 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. Ecco una richiesta di esempio.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

Per il valore _ ID tenant nei parametri Post URI e client * _ ID* e client _ Secret specificare l'ID tenant, l'ID client e la chiave per l'applicazione recuperata dal centro per i partner nella sezione precedente.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. Per il parametro resource è necessario specificare https://manage.devcenter.microsoft.com.For the resource parameter, you must specify https://manage.devcenter.microsoft.com.

Dopo la scadenza del token di accesso, puoi aggiornarlo seguendo le istruzioni disponibili qui.After your access token expires, you can refresh it by following the instructions here.

Passaggio 3: chiamare l'API delle promozioni Microsoft StoreStep 3: Call the Microsoft Store promotions API

Una volta che si dispone di un token di accesso Azure AD, è possibile chiamare l'API delle promozioni Microsoft Store.After you have an Azure AD access token, you are ready to call the Microsoft Store promotions API. Devi passare il token di accesso all’intestazione Authorization di ogni metodo.You must pass the access token to the Authorization header of each method.

Nel contesto dell'API Microsoft Store Promotion, una campagna di Active Directory è costituita da un oggetto Campaign che contiene informazioni generali sulla campagna e da oggetti aggiuntivi che rappresentano le linee di consegna, i profili di destinazionee le creatività per la campagna pubblicitaria.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. L'API include diversi set di metodi raggruppati in base a questi tipi di oggetto.The API includes different sets of methods that are grouped by these object types. Per creare una campagna, in genere si chiama un metodo POST diverso per ognuno di questi oggetti.To create a campaign, you typically call a different POST method for each of these objects. L'API fornisce anche metodi GET che è possibile usare per recuperare tutti gli oggetti e i metodi PUT che è possibile usare per modificare la campagna, la linea di recapito e gli oggetti del profilo di destinazione.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.

Per ulteriori informazioni su questi oggetti e sui relativi metodi, vedere la tabella seguente.For more information about these objects and their related methods, see the following table.

OggettoObject DescrizioneDescription
CampagneCampaigns Questo oggetto rappresenta la campagna di Active Directory e si trova nella parte superiore della gerarchia del modello a oggetti per le campagne pubblicitarie.This object represents the ad campaign, and it sits at the top of the object model hierarchy for ad campaigns. Questo oggetto identifica il tipo di campagna in esecuzione (a pagamento, abitazione o community), l'obiettivo della campagna, le linee di consegna per la campagna e altri dettagli.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. Ogni campagna può essere associata a una sola app.Each campaign can be associated with only one app.

Per ulteriori informazioni sui metodi correlati a questo oggetto, vedere Manage ad Campaigns.For more information about the methods related to this object, see Manage ad campaigns.

Note   Nota   Dopo aver creato una campagna di Active Directory, è possibile recuperare i dati sulle prestazioni per la campagna usando il metodo Get ad campaign performance data nel Microsoft Store API Analytics.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.
Righe di recapitoDelivery lines Ogni campagna ha una o più linee di consegna che vengono usate per acquistare l'inventario e fornire gli annunci.Every campaign has one or more delivery lines that are used to buy inventory and deliver your ads. Per ogni linea di consegna, è possibile impostare il targeting, impostare il prezzo dell'offerta e decidere la quantità di spesa impostando un budget e il collegamento alle creatività che si vuole usare.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.

Per ulteriori informazioni sui metodi correlati a questo oggetto, vedere Manage recapito lines for ad Campaigns.For more information about the methods related to this object, see Manage delivery lines for ad campaigns.
Profili di destinazioneTargeting profiles Ogni linea di recapito dispone di un profilo di destinazione che specifica gli utenti, le aree geografiche e i tipi di inventario di destinazione.Every delivery line has one targeting profile that specifies the users, geographies and inventory types that you want to target. I profili di destinazione possono essere creati come modello e condivisi tra più righe di recapito.Targeting profiles can be created as a template and shared across delivery lines.

Per ulteriori informazioni sui metodi correlati a questo oggetto, vedere Manage targeting Profiles for ad Campaigns.For more information about the methods related to this object, see Manage targeting profiles for ad campaigns.
CreativiCreatives Ogni linea di consegna ha una o più creatività che rappresentano gli annunci visualizzati ai clienti come parte della campagna.Every delivery line has one or more creatives that represent the ads that are shown to customers as part of the campaign. Una creatività può essere associata a una o più linee di recapito, anche attraverso campagne pubblicitarie, purché rappresenti sempre la stessa app.A creative may be associated with one or more delivery lines, even across ad campaigns, provided it always represents the same app.

Per ulteriori informazioni sui metodi correlati a questo oggetto, vedere Manage Creatives for ad Campaigns.For more information about the methods related to this object, see Manage creatives for ad campaigns.

Il diagramma seguente illustra la relazione tra le campagne, le linee di recapito, i profili di destinazione e le creatività.The following diagram illustrates the relationship between campaigns, delivery lines, targeting profiles, and creatives.

Gerarchia della campagna ad

Esempio di codiceCode example

Nell'esempio di codice riportato di seguito viene illustrato come ottenere un token di accesso Azure AD e chiamare l'API di Microsoft Store Promotions da un'applicazione console C#.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. Per usare questo esempio di codice, assegna le variabili tenantId, clientId, clientSecret e appID ai valori appropriati per il tuo scenario.To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. Questo esempio richiede il pacchetto JSON.NET di Newtonsoft per deserializzare i dati JSON restituiti dall'API Microsoft Store Promotions.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;
        }
    }
}