Instruções: Aplicação Web da API de Anúncios do Bing em C#

Artigo
12/21/2023

Este exemplo de aplicação Web C# pede o consentimento do utilizador através das credenciais que fornecer e, em seguida, obtém as contas às quais o utilizador autenticado pode aceder.

Primeiro, tem de registar uma aplicação e anotar o ID de cliente (ID da aplicação registada), o segredo do cliente (palavra-passe registada) e o URI de redirecionamento. Para obter mais detalhes sobre o registo de uma aplicação e o fluxo de concessão de código de autorização, veja Authentication with OAuth (Autenticação com OAuth).

Também precisará do token de programador de produção. Pode criar o exemplo passo a passo, conforme descrito abaixo, ou transferir mais exemplos do GitHub.

Sugestão

Este exemplo faz referência aos passos de Criar uma aplicação Web do ASP.NET Framework no Azure. Para obter mais detalhes sobre como implementar aplicações Web no Azure, veja a documentação do Azure.

Instruções de Código

Abra o ambiente de desenvolvimento Visual Studio Community 2017. Se já instalou o Visual Studio, adicione o ASP.NET e o desenvolvimento Web e as cargas de trabalho de desenvolvimento do Azure no Visual Studio ao clicar em Ferramentas Obter Ferramentas>e Funcionalidades.
Crie um novo projeto ao selecionar Ficheiro > Novo > Projeto. Na janela Novo Projeto, selecione .NET Framework 4.7.1 no menu pendente e, em seguida, selecione Visual C# > Web > ASP.NET Web Application (.NET Framework). Atribua um nome ao projeto BingAdsWebApp e clique em OK.
Pode implementar qualquer tipo de ASP.NET aplicação Web no Azure. Para este início rápido, selecione o modelo MVC , certifique-se de que a autenticação está definida como Sem Autenticação e clique em OK.
Instale o SDK através do NuGet para o BingAdsWebApp. Para obter mais informações sobre dependências, veja Instalar o SDK. Clique em Ferramentas ->Gestor de Pacotes NuGet ->Consola do Gestor de Pacotes. Na linha de comandos, escreva estes comandos para instalar os pacotes um de cada vez: Install-Package Microsoft.BingAds.SDK, Install-Package System.ServiceModel.Primitives -Version 4.4.1, Install-Package System.ServiceModel.Http -Version 4.4.1e Install-Package System.Configuration.ConfigurationManager -Version 4.4.1.
Abra o ficheiro Web.config e substitua o respetivo conteúdo pelo seguinte bloco de código. Edite o BingAdsEnvironment para passar do sandbox para a produção e defina o token de programador de produção conforme necessário. Tem de editar o ClientId, o ClientSecret e o RedirectionUri com os valores de ID da Aplicação, Segredo da Aplicação e URL de Redirecionamento correspondentes que foram aprovisionados quando registou a aplicação.

Nota

Se pretender implementar no localhost antes de entrar em direto, certifique-se de que também regista o URL e a porta SSL locais, por exemplo, https://localhost:44383/. Nesse caso, também tem de definir SSL Ativado como Verdadeiro na janela de propriedades do projeto BingAdsWebApp e, em seguida, pode copiar a porta localhost a partir da mesma janela de propriedades.

  <?xml version="1.0" encoding="utf-8"?>
  <!--
      For more information on how to configure your ASP.NET application, please visit
      https://go.microsoft.com/fwlink/?LinkId=301880
      -->
  <configuration>
      <configSections>
      <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">
          <section name="BingAdsWebApp.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" />
      </sectionGroup>
      </configSections>
      <appSettings>
      <!-- To use the production environment, set this value to "Production". -->
      <add key="BingAdsEnvironment" value="Sandbox"/>
      <add key="webpages:Version" value="3.0.0.0" />
      <add key="webpages:Enabled" value="false" />
      <add key="ClientValidationEnabled" value="true" />
      <add key="UnobtrusiveJavaScriptEnabled" value="true" />
      </appSettings>
      <system.web>
      <compilation debug="true" targetFramework="4.7.1" />
      <httpRuntime targetFramework="4.7.1" />
      <httpModules>
          <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
      </httpModules>
      </system.web>
      <runtime>
      <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
          <dependentAssembly>
          <assemblyIdentity name="Newtonsoft.Json" culture="neutral" publicKeyToken="30ad4fe6b2a6aeed" />
          <bindingRedirect oldVersion="0.0.0.0-6.0.0.0" newVersion="6.0.0.0" />
          </dependentAssembly>
          <dependentAssembly>
          <assemblyIdentity name="System.Web.Optimization" publicKeyToken="31bf3856ad364e35" />
          <bindingRedirect oldVersion="1.0.0.0-1.1.0.0" newVersion="1.1.0.0" />
          </dependentAssembly>
          <dependentAssembly>
          <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
          <bindingRedirect oldVersion="0.0.0.0-1.5.2.14234" newVersion="1.5.2.14234" />
          </dependentAssembly>
          <dependentAssembly>
          <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
          <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
          </dependentAssembly>
          <dependentAssembly>
          <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
          <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
          </dependentAssembly>
          <dependentAssembly>
          <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
          <bindingRedirect oldVersion="1.0.0.0-5.2.3.0" newVersion="5.2.3.0" />
          </dependentAssembly>
      </assemblyBinding>
      </runtime>
      <system.webServer>
      <validation validateIntegratedModeConfiguration="false" />
      <modules>
          <remove name="ApplicationInsightsWebTracking" />
          <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />
      </modules>
      </system.webServer>
      <system.codedom>
      <compilers>
          <compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.CSharpCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=1.0.7.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:1659;1699;1701" />
          <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.VBCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=1.0.7.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:41008 /define:_MYTYPE=\&quot;Web\&quot; /optionInfer+" />
      </compilers>
      </system.codedom>
      <applicationSettings>
      <BingAdsWebApp.Properties.Settings>
          <setting name="RefreshToken" serializeAs="String">
          <value />
          </setting>
          <setting name="ClientId" serializeAs="String">
          <value>ClientIdGoesHere</value>
          </setting>
          <setting name="ClientSecret" serializeAs="String">
          <value>ClientSecretGoesHere</value>
          </setting>
          <setting name="RedirectionUri" serializeAs="String">
          <value>RedirectionUriGoesHere</value>
          </setting>
          <setting name="DeveloperToken" serializeAs="String">
          <value>DeveloperTokenGoesHere</value>
          </setting>
      </BingAdsWebApp.Properties.Settings>
      </applicationSettings>
  </configuration>

Crie um ficheiro de definições. Na vista de projeto do BingAdsWebApp, clique com o botão direito do rato em Propriedades e clique em Abrir. Clique em Definições e, em seguida, clique no texto O projeto não contém um ficheiro de predefinições. Clique aqui para criar um. Serão adicionados automaticamente novos valores de Web.config.
Na pasta Views ->Home do projeto BingAdsWebApp, abra o ficheiro Index.cshtml e substitua os respetivos conteúdos pelo seguinte bloco de código. Isto define a vista de página Web que apresenta os resultados das chamadas de serviço que serão escritas mais abaixo.
```
@{
    ViewBag.Title = "Index";
}

<h2>Index</h2>

<h4>Accounts</h4>
<p>@Html.Raw(@ViewBag.Accounts)</p>

<p><b style="color: red">@ViewBag.Errors</b></p>
```

Na pasta Controllers (Controladores ) do projeto BingAdsWebApp, abra o ficheiro HomeController.cs e substitua os respetivos conteúdos pelo seguinte bloco de código. Isto define as chamadas de serviço que determinarão que resultados são apresentados na vista que foi definida acima.

using System;
using System.Collections.Generic;
using System.Configuration;
using System.Linq;
using System.Net.Http;
using System.ServiceModel;
using System.Threading.Tasks;
using System.Web.Mvc;
using BingAdsWebApp.Properties;
using Microsoft.BingAds;
using Microsoft.BingAds.V13.CustomerManagement;

namespace BingAdsWebApp.Controllers
{
    public class HomeController : Controller
    {
        private static AuthorizationData _authorizationData;
        private static ServiceClient<ICustomerManagementService> _customerManagementService;
        private static string ClientState = "ClientStateGoesHere";
        private static string _output = "";

        /// <summary>
        /// Controls the contents displayed at Index.cshtml.
        /// </summary>
        public async Task<ActionResult> Index()
        {
            try
            {
                // If there is already an authenticated Microsoft account during this HTTP session, 
                // go ahead and call Bing Ads API service operations.

                if (Session["auth"] != null)
                {
                    return await SetAuthorizationDataAsync((OAuthWebAuthCodeGrant)Session["auth"]);
                }

                // Prepare the OAuth object for use with the authorization code grant flow. 

                var apiEnvironment =
                    ConfigurationManager.AppSettings["BingAdsEnvironment"] == ApiEnvironment.Sandbox.ToString() ?
                    ApiEnvironment.Sandbox : ApiEnvironment.Production;
                var oAuthWebAuthCodeGrant = new OAuthWebAuthCodeGrant(
                    Settings.Default["ClientId"].ToString(),
                    Settings.Default["ClientSecret"].ToString(), 
                    new Uri(Settings.Default["RedirectionUri"].ToString()),
                    apiEnvironment);

                // It is recommended that you specify a non guessable 'state' request parameter to help prevent
                // cross site request forgery (CSRF). 
                oAuthWebAuthCodeGrant.State = ClientState;

                // When calling Bing Ads API service operations with ServiceClient or BulkServiceManager, each will refresh your access token 
                // automatically if they detect the AuthenticationTokenExpired (109) error code. 
                // As a best practice you should always use the most recent provided refresh token.
                // Save the refresh token whenever new OAuth tokens are received by subscribing to the NewOAuthTokensReceived event handler. 

                oAuthWebAuthCodeGrant.NewOAuthTokensReceived +=
                    (sender, args) => SaveRefreshToken(args.NewRefreshToken);

                // If a refresh token is already present, use it to request new access and refresh tokens.

                if (RefreshTokenExists())
                {
                    await oAuthWebAuthCodeGrant.RequestAccessAndRefreshTokensAsync(GetRefreshToken());

                    // Save the authentication object in a session for future requests.
                    Session["auth"] = oAuthWebAuthCodeGrant;

                    return await SetAuthorizationDataAsync((OAuthWebAuthCodeGrant)Session["auth"]);
                }

                // If the current HTTP request is a callback from the Microsoft Account authorization server,
                // use the current request url containing authorization code to request new access and refresh tokens
                if (Request["code"] != null)
                {
                    if (oAuthWebAuthCodeGrant.State != ClientState)
                        throw new HttpRequestException("The OAuth response state does not match the client request state.");

                    await oAuthWebAuthCodeGrant.RequestAccessAndRefreshTokensAsync(Request.Url);

                    // Save the authentication object in a session for future requests. 
                    Session["auth"] = oAuthWebAuthCodeGrant;

                    return await SetAuthorizationDataAsync((OAuthWebAuthCodeGrant)Session["auth"]);
                }

                SaveRefreshToken(oAuthWebAuthCodeGrant.OAuthTokens?.RefreshToken);

                // If there is no refresh token saved and no callback from the authorization server, 
                // then connect to the authorization server and request user consent. 
                return Redirect(oAuthWebAuthCodeGrant.GetAuthorizationEndpoint().ToString());
            }
            // Catch authentication exceptions
            catch (OAuthTokenRequestException ex)
            {
                ViewBag.Errors = (string.Format("Couldn't get OAuth tokens. Error: {0}. Description: {1}", 
                    ex.Details.Error, ex.Details.Description));
                return View();
            }
            // Catch Customer Management service exceptions
            catch (FaultException<Microsoft.BingAds.V13.CustomerManagement.AdApiFaultDetail> ex)
            {
                ViewBag.Errors = (string.Join("; ", ex.Detail.Errors.Select(
                    error => string.Format("{0}: {1}", error.Code, error.Message))));
                return View();
            }
            catch (FaultException<Microsoft.BingAds.V13.CustomerManagement.ApiFault> ex)
            {
                ViewBag.Errors = (string.Join("; ", ex.Detail.OperationErrors.Select(
                    error => string.Format("{0}: {1}", error.Code, error.Message))));
                return View();
            }            
            catch (Exception ex)
            {
                ViewBag.Errors = ex.Message;
                return View();
            }
        }

        /// <summary>
        /// Adds a campaign to an account of the current authenticated user. 
        /// </summary>
        private async Task<ActionResult> SetAuthorizationDataAsync(Authentication authentication)
        {
            _authorizationData = new AuthorizationData
            {
                Authentication = authentication,
                DeveloperToken = Settings.Default["DeveloperToken"].ToString()
            };

            _customerManagementService = new ServiceClient<ICustomerManagementService>(_authorizationData);

            var getUserRequest = new GetUserRequest
            {
                UserId = null
            };

            var getUserResponse = 
                (await _customerManagementService.CallAsync((s, r) => s.GetUserAsync(r), getUserRequest));
            var user = getUserResponse.User;

            var predicate = new Predicate
            {
                Field = "UserId",
                Operator = PredicateOperator.Equals,
                Value = user.Id.ToString()
            };

            var paging = new Paging
            {
                Index = 0,
                Size = 10
            };

            var searchAccountsRequest = new SearchAccountsRequest
            {
                Ordering = null,
                PageInfo = paging,
                Predicates = new[] { predicate }
            };

            var searchAccountsResponse =
                (await _customerManagementService.CallAsync((s, r) => s.SearchAccountsAsync(r), searchAccountsRequest));

            var accounts = searchAccountsResponse.Accounts.ToArray();
            if (accounts.Length <= 0) return View();

            _authorizationData.AccountId = (long)accounts[0].Id;
            _authorizationData.CustomerId = (int)accounts[0].ParentCustomerId;

            OutputArrayOfAdvertiserAccount(accounts);

            ViewBag.Accounts = _output;
            _output = null;

            return View();
        }

        /// <summary>
        /// Saves the refresh token
        /// </summary>
        /// <param name="refreshToken">The refresh token to save</param>
        private static void SaveRefreshToken(string refreshToken)
        {
            Settings.Default["RefreshToken"] = refreshToken;
            Settings.Default.Save();
        }

        /// <summary>
        /// Deletes the contents in the refresh token file
        /// </summary>
        private static void DeleteRefreshToken()
        {
            Settings.Default["RefreshToken"] = "";
            Settings.Default.Save();
        }

        /// <summary>
        /// Determines whether the global refresh token exists.
        /// </summary>
        /// <returns>Returns true if the global refresh token exists.</returns>
        private bool RefreshTokenExists()
        {
            return Settings.Default["RefreshToken"] != null 
                && Settings.Default["RefreshToken"].ToString().Length > 0;
        }

        /// <summary>
        /// Gets the global refresh token.
        /// </summary>
        /// <returns>The global refresh token.</returns>
        private string GetRefreshToken()
        {
            return Settings.Default["RefreshToken"].ToString();
        }

        #region OutputHelpers

        /**
         * You can extend the app with example output helpers at:
         * https://github.com/BingAds/BingAds-dotNet-SDK/tree/main/examples/BingAdsExamples/BingAdsExamplesLibrary/v13
         * 
         * AdInsightExampleHelper.cs
         * BulkExampleHelper.cs
         * CampaignManagementExampleHelper.cs
         * CustomerBillingExampleHelper.cs
         * CustomerManagementExampleHelper.cs
         * ReportingExampleHelper.cs
         **/

        private static void OutputArrayOfAdvertiserAccount(IList<AdvertiserAccount> dataObjects)
        {
            if (null != dataObjects)
            {
                foreach (var dataObject in dataObjects)
                {
                    OutputAdvertiserAccount(dataObject);
                    OutputStatusMessage("\n");
                }
            }
        }

        private static void OutputAdvertiserAccount(AdvertiserAccount dataObject)
        {
            if (null != dataObject)
            {
                OutputStatusMessage(string.Format("BillToCustomerId: {0}", dataObject.BillToCustomerId));
                OutputStatusMessage(string.Format("CurrencyCode: {0}", dataObject.CurrencyCode));
                OutputStatusMessage(string.Format("AccountFinancialStatus: {0}", dataObject.AccountFinancialStatus));
                OutputStatusMessage(string.Format("Id: {0}", dataObject.Id));
                OutputStatusMessage(string.Format("Language: {0}", dataObject.Language));
                OutputStatusMessage(string.Format("LastModifiedByUserId: {0}", dataObject.LastModifiedByUserId));
                OutputStatusMessage(string.Format("LastModifiedTime: {0}", dataObject.LastModifiedTime));
                OutputStatusMessage(string.Format("Name: {0}", dataObject.Name));
                OutputStatusMessage(string.Format("Number: {0}", dataObject.Number));
                OutputStatusMessage(string.Format("ParentCustomerId: {0}", dataObject.ParentCustomerId));
                OutputStatusMessage(string.Format("PaymentMethodId: {0}", dataObject.PaymentMethodId));
                OutputStatusMessage(string.Format("PaymentMethodType: {0}", dataObject.PaymentMethodType));
                OutputStatusMessage(string.Format("PrimaryUserId: {0}", dataObject.PrimaryUserId));
                OutputStatusMessage(string.Format("AccountLifeCycleStatus: {0}", dataObject.AccountLifeCycleStatus));
                OutputStatusMessage(string.Format("TimeStamp: {0}", dataObject.TimeStamp));
                OutputStatusMessage(string.Format("TimeZone: {0}", dataObject.TimeZone));
                OutputStatusMessage(string.Format("PauseReason: {0}", dataObject.PauseReason));
                OutputArrayOfKeyValuePairOfstringstring(dataObject.ForwardCompatibilityMap);
                OutputArrayOfCustomerInfo(dataObject.LinkedAgencies);
                OutputStatusMessage(string.Format("SalesHouseCustomerId: {0}", dataObject.SalesHouseCustomerId));
                OutputArrayOfKeyValuePairOfstringstring(dataObject.TaxInformation);
                OutputStatusMessage(string.Format("BackUpPaymentInstrumentId: {0}", dataObject.BackUpPaymentInstrumentId));
                OutputStatusMessage(string.Format("BillingThresholdAmount: {0}", dataObject.BillingThresholdAmount));
                OutputAddress(dataObject.BusinessAddress);
                OutputStatusMessage(string.Format("AutoTagType: {0}", dataObject.AutoTagType));
                OutputStatusMessage(string.Format("SoldToPaymentInstrumentId: {0}", dataObject.SoldToPaymentInstrumentId));
            }
        }

        private static void OutputAddress(Address dataObject)
        {
            if (null != dataObject)
            {
                OutputStatusMessage(string.Format("City: {0}", dataObject.City));
                OutputStatusMessage(string.Format("CountryCode: {0}", dataObject.CountryCode));
                OutputStatusMessage(string.Format("Id: {0}", dataObject.Id));
                OutputStatusMessage(string.Format("Line1: {0}", dataObject.Line1));
                OutputStatusMessage(string.Format("Line2: {0}", dataObject.Line2));
                OutputStatusMessage(string.Format("Line3: {0}", dataObject.Line3));
                OutputStatusMessage(string.Format("Line4: {0}", dataObject.Line4));
                OutputStatusMessage(string.Format("PostalCode: {0}", dataObject.PostalCode));
                OutputStatusMessage(string.Format("StateOrProvince: {0}", dataObject.StateOrProvince));
                OutputStatusMessage(string.Format("TimeStamp: {0}", dataObject.TimeStamp));
                OutputStatusMessage(string.Format("BusinessName: {0}", dataObject.BusinessName));
            }
        }

        private static void OutputArrayOfKeyValuePairOfstringstring(IList<KeyValuePair<string, string>> dataObjects)
        {
            if (null != dataObjects)
            {
                foreach (var dataObject in dataObjects)
                {
                    OutputKeyValuePairOfstringstring(dataObject);
                }
            }
        }

        private static void OutputKeyValuePairOfstringstring(KeyValuePair<string, string> dataObject)
        {
            if (null != dataObject.Key)
            {
                OutputStatusMessage(string.Format("key: {0}", dataObject.Key));
                OutputStatusMessage(string.Format("value: {0}", dataObject.Value));
            }
        }

        private static void OutputCustomerInfo(CustomerInfo dataObject)
        {
            if (null != dataObject)
            {
                OutputStatusMessage(string.Format("Id: {0}", dataObject.Id));
                OutputStatusMessage(string.Format("Name: {0}", dataObject.Name));
            }
        }

        private static void OutputArrayOfCustomerInfo(IList<CustomerInfo> dataObjects)
        {
            if (null != dataObjects)
            {
                foreach (var dataObject in dataObjects)
                {
                    OutputCustomerInfo(dataObject);
                    OutputStatusMessage("\n");
                }
            }
        }

        private static void OutputStatusMessage(String msg)
        {
            _output += (msg + "<br/>");
        }

        #endregion OutputHelpers
    }
}

Para implementar a aplicação Web no computador local, primeiro tem de definir SSL Ativado como Verdadeiro na janela de propriedades do projeto BingAdsWebApp. Se ainda não o fez, o URL de redirecionamento da aplicação registada tem de incluir o URL de SSL e a porta, por exemplo, https://localhost:44383/. No menu, selecione Depurar > Iniciar sem Depurar para executar a aplicação Web localmente.
Para implementar a sua aplicação Web em direto com o Serviço de Aplicações do Azure veja as instruções de subscrição e implementação na documentação do Azure, por exemplo, Criar uma aplicação Web do ASP.NET Framework no Azure.

Configurar o Sandbox

Para utilizar o sandbox, defina a chave BingAdsEnvironment como Sandbox no <nó appSettings> do ficheiro Web.config da raiz do projeto.

<add key="BingAdsEnvironment" value ="Sandbox"/>

Também pode definir o ambiente para cada ServiceClient individualmente da seguinte forma.

_customerService = new ServiceClient<ICustomerManagementService>(_authorizationData, ApiEnvironment.Sandbox);

Quer defina o ambiente ServiceClient global ou individualmente, também terá de definir o ambiente OAuth como sandbox.

var oAuthWebAuthCodeGrant = new OAuthWebAuthCodeGrant(ClientId, ClientSecret, new Uri(RedirectionUri), ApiEnvironment.Sandbox);

Partilhar via

Instruções: Aplicação Web da API de Anúncios do Bing em C#

Instruções de Código

Configurar o Sandbox

See Also

Comentários

Recursos adicionais