Compartir a través de

Autenticación con los SDK

  • Artículo

En este artículo se tratan la autenticación y las llamadas de servicio básicas con los SDK de Bing Ads.

Configuración del espacio aislado

El SDK usa el entorno de producción de forma predeterminada. Con los SDK de .NET y Java, puede cambiarlo a espacio aislado con una configuración global. Mientras que la configuración global no está disponible con los SDK de PHP y Python, puede crear una configuración global u otra solución personalizada.

// Set the BingAdsEnvironment key to Sandbox within the <appSettings> node 
// of your project root's Web.config file (for web apps) or App.config file (for native apps).
<add key="BingAdsEnvironment" value ="Sandbox"/>

// Create a new text file named bingads.properties within your project source root directory 
// e.g. **ProjectName\src\bingads.properties** and add only the following text. 
// If the sandbox environment setting is malformed or missing, the default environment is production.
environment=Sandbox

También puede establecer el parámetro de entorno de API de instancias de Service Manager masivas individuales, cliente de servicio e instancias de Service Manager de informes. Al establecer apiEnvironment , se invalida la configuración global solo para la instancia o las instancias de cliente de servicio especificadas. A menos que se pretenda lo contrario, debe tener cuidado de no configurar involuntariamente un conjunto mixto de entornos.

Nota:

BulkServiceManager y ReportingServiceManager están disponibles con los SDK de .NET, Java y Python.

BulkServiceManager BulkService = new BulkServiceManager(authorizationData, ApiEnvironment.Sandbox);

ServiceClient<ICustomerManagementService> Service = new ServiceClient<ICustomerManagementService>(authorizationData, ApiEnvironment.Sandbox);
    
ReportingServiceManager ReportingService = new ReportingServiceManager(authorizationData, ApiEnvironment.Sandbox);

BulkServiceManager BulkService = new BulkServiceManager(authorizationData, ApiEnvironment.SANDBOX);

ServiceClient<ICustomerManagementService> CustomerService = 
    new ServiceClient<ICustomerManagementService>(
        authorizationData,
        ApiEnvironment.SANDBOX,
        ICustomerManagementService.class
    );
    
ReportingServiceManager ReportingService = new ReportingServiceManager(authorizationData, ApiEnvironment.SANDBOX);

$customerProxy = new ServiceClient(ServiceClientType::CustomerManagementVersion13, $authorizationData, ApiEnvironment::Sandbox);

# Set the environment property of each ServiceClient instance to 'sandbox' (not case sensitive). 
# If the sandbox environment setting is malformed or missing, the default environment is production.
# Once the environment is initialized you may not reset it for the service client instance. 
# To switch between sandbox and production, you must create a new service client instance.

bulk_service_manager = BulkServiceManager(
    authorization_data=authorization_data, 
    version = 13,
    poll_interval_in_milliseconds = 5000, 
    environment = 'sandbox',
)

customer_service = ServiceClient(
    'CustomerManagementService', 
    version = 13,
    authorization_data=authorization_data, 
    environment = 'sandbox',
)

reporting_service_manager = ReportingServiceManager(
    authorization_data=authorization_data, 
    version = 13,
    poll_interval_in_milliseconds = 5000, 
    environment = 'sandbox',
)

Uso de OAuth

Los SDK de Bing Ads admiten el flujo estándar de OAuth 2.0, tal como se define en detalle en El marco de autorización de OAuth 2.0. Las clases OAuth del SDK abstraen los detalles de autorización de usuario de bajo nivel, como dar formato a los URI de autorización y redireccionamiento, establecer los encabezados de solicitud y analizar el tráfico de redireccionamiento y el flujo de respuesta. Para usar OAuth con el SDK de .NET de Bing Ads, la propiedad Authentication del objeto AuthorizationData debe establecerse en una clase derivada de authentication, como OAuthWebAuthCodeGrant, OAuthDesktopMobileAuthCodeGrant o OAuthDesktopMobileImplicitGrant.

Para la autenticación repetida o a largo plazo, debe seguir el flujo de concesión de código de autorización para obtener un token de acceso. Los pasos siguientes siguen el flujo de concesión de código de autorización. Para obtener más información sobre cómo registrar una aplicación y el flujo de concesión de código de autorización, consulte Autenticación con OAuth.

  1. Cree una instancia de OAuthWebAuthCodeGrant, que se usará para administrar la autorización de usuario de la cuenta Microsoft. Reemplace el identificador de cliente (id. de aplicación registrado), el secreto de cliente (contraseña registrada) y el URI de redireccionamiento por los valores configurados al registrar la aplicación.

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

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

    OAuthWebAuthCodeGrant oAuthWebAuthCodeGrant = new OAuthWebAuthCodeGrant(ClientId, ClientSecret, new URL(RedirectionUri), ApiEnvironment);

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

    // Prepare the OAuth object for use with the authorization code grant flow. 
// It is recommended that you specify a non guessable 'state' request parameter to help prevent
// cross site request forgery (CSRF). 
$authentication = (new OAuthWebAuthCodeGrant())
    ->withClientId(ClientId)
    ->withClientSecret(ClientSecret)
    ->withEnvironment(ApiEnvironment)
    ->withRedirectUri('https://' . $_SERVER['HTTP_HOST'] . RedirectUri)
    ->withState(rand(0,999999999)); 

// Assign this authentication instance to the global authorization_data. 

$_SESSION['AuthorizationData'] = (new AuthorizationData())
    ->withAuthentication($authentication)
    ->withDeveloperToken(AuthHelper::DeveloperToken);

$_SESSION['state'] = $_SESSION['AuthorizationData']->Authentication->State;

    oauth_web_auth_code_grant = OAuthWebAuthCodeGrant(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
    env=ENVIRONMENT,
    redirection_uri=REDIRECTION_URI
)

# It is recommended that you specify a non guessable 'state' request parameter to help prevent
# cross site request forgery (CSRF). 
oauth_web_auth_code_grant.state="ClientStateGoesHere"

  2. Solicite el consentimiento del usuario mediante la conexión al punto de conexión de autorización de la cuenta Microsoft a través de un control de explorador web. Llame al método GetAuthorizationEndpoint de la instancia de OAuthWebAuthCodeGrant que creó en el paso anterior.

    return Redirect(oAuthWebAuthCodeGrant.GetAuthorizationEndpoint().ToString());

    URL authorizationEndpoint = oAuthWebAuthCodeGrant.getAuthorizationEndpoint();
response.sendRedirect(authorizationEndpoint.toString());

    // The user needs to provide consent for the application to access their Microsoft Advertising accounts.
header('Location: '. $_SESSION['AuthorizationData']->Authentication->GetAuthorizationEndpoint());

    oauth_web_auth_code_grant.get_authorization_endpoint()

    Se pedirá al usuario a través del control del explorador web de autorización de la cuenta microsoft que conceda permisos para que la aplicación administre sus cuentas de Microsoft Advertising.

    El servicio de autorización vuelve a llamar a la aplicación con el URI de redirección, que incluye un código de autorización si el usuario autorizó a la aplicación a administrar sus cuentas de Microsoft Advertising. Por ejemplo, la dirección URL de devolución de llamada incluye un código de autorización como se indica a continuación si el usuario concedió permisos a la aplicación para administrar sus cuentas de Microsoft Advertising: https://contoso.com/redirect/?code=CODE& state=ClientStateGoesHere. Si el usuario concedió a la aplicación permisos para administrar sus cuentas de Microsoft Advertising, debe usar el código inmediatamente en el paso siguiente. La breve duración del código de autorización, aproximadamente 5 minutos, está sujeta a cambios.

    Si el usuario denegó los permisos de la aplicación para administrar sus cuentas de Microsoft Advertising, el URI de devolución de llamada incluye un campo de descripción de error y error como se indica a continuación: REDIRECTURI?error=access_denied&error_description=ERROR_DESCRIPTION&state=ClientStateGoesHere.

  3. Use el código de autorización para solicitar el token de acceso y el token de actualización. Pase el URI de devolución de llamada completo al usar la instancia de OAuthWebAuthCodeGrant para solicitar el token de acceso y el token de actualización.

    if (Request["code"] != null)
{
    await oAuthWebAuthCodeGrant.RequestAccessAndRefreshTokensAsync(Request.Url);
}

    if (request.getParameter("code") != null)
{
    oAuthWebAuthCodeGrant.requestAccessAndRefreshTokens(new URL(request.getRequestURL() + "?" + request.getQueryString()));
}

    if($_GET['code'] != null)
{   
    $_SESSION['AuthorizationData']->Authentication->RequestOAuthTokensByResponseUri($_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']);

    header('Location: '. '/CallBingAdsServices.php');
}

    oauth_web_auth_code_grant.request_oauth_tokens_by_response_uri(RESPONSE_URI)
oauth_tokens = oauth_web_auth_code_grant.oauth_tokens
access_token = oauth_tokens.access_token

    Si este paso se ha realizado correctamente, la aplicación tiene permisos para administrar las cuentas de Microsoft Advertising del usuario. Para llamar a las operaciones del servicio api de Bing Ads, debe inicializar service client, bulk Service Manager o reporting Service Manager con AuthorizationData que contenga la instancia de OAuthWebAuthCodeGrant.

    Para obtener más información, vea Uso de AuthorizationData, Uso del cliente de servicio, Uso de BulkServiceManager y Uso de ReportingServiceManager.

    Nota:

    BulkServiceManager y ReportingServiceManager están disponibles con los SDK de .NET, Java y Python.

  4. Al llamar a las operaciones del servicio api de Bing Ads con Service Client, Service Manager masiva o Service Manager de informes, es importante guardar el token de actualización más reciente cada vez que se reciban nuevos tokens de OAuth.

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

if (GetRefreshToken(out refreshToken))
{
    oAuthWebAuthCodeGrant.RequestAccessAndRefreshTokensAsync(refreshToken);
}

// When calling Bing Ads API service operations with Service Client, Bulk Service Manager, or Reporting Service Manager, 
// each instance will refresh your access token automatically if they detect the AuthenticationTokenExpired (109) error code. 
// It is important to save the most recent refresh token whenever new OAuth tokens are received. 
// You will want to subscribe to the NewOAuthTokensReceived event handler.

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

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

if (refreshToken != null)
{
    oAuthWebAuthCodeGrant.requestAccessAndRefreshTokens(refreshToken);
}

// When calling Bing Ads API service operations with Service Client, Bulk Service Manager, or Reporting Service Manager, 
// each instance will refresh your access token automatically if they detect the AuthenticationTokenExpired (109) error code. 
// It is important to save the most recent refresh token whenever new OAuth tokens are received. 
// You will want to implement event handling using the NewOAuthTokensReceivedListener.

oAuthWebAuthCodeGrant.setNewTokensListener(new NewOAuthTokensReceivedListener() {
    @Override
    public void onNewOAuthTokensReceived(OAuthTokens newTokens) {
           saveRefreshToken(newTokens.getRefreshToken());
    }
});

    // If you already have a refresh token, use it to request new access and refresh tokens.
$_SESSION['AuthorizationData']->Authentication->RequestOAuthTokensByRefreshToken($refreshToken);

    # When calling Bing Ads API service operations with Service Client, Bulk Service Manager, or Reporting Service Manager, 
# each instance will refresh your access token automatically if they detect the AuthenticationTokenExpired (109) error code. 
# It is important to save the most recent refresh token whenever new OAuth tokens are received. 
# You will want to register a callback function to automatically save the refresh token anytime it is refreshed. 
# For example if you defined have a save_refresh_token() method that securely stores your refresh token, 
# set the authentication token_refreshed_callback property of each OAuthWebAuthCodeGrant instance.

oauth_web_auth_code_grant.token_refreshed_callback=save_refresh_token

# If you already have a refresh token, use it to request new access and refresh tokens.

if refresh_token is not None:
    oauth_web_auth_code_grant.request_oauth_tokens_by_refresh_token(refresh_token)

    Importante

    Un token de actualización puede durar hasta 90 días. Independientemente, debe esperar volver a empezar desde el paso 1 y solicitar el consentimiento del usuario si, por ejemplo, el usuario de la cuenta Microsoft cambió su contraseña, quitó un dispositivo de su lista de dispositivos de confianza o quitó permisos para que la aplicación se autentique en su nombre.

Uso de AuthorizationData

La clase AuthorizationData contiene propiedades que Microsoft Advertising usa para autorizar a un usuario. Las clases Service Client, Bulk Service Manager y Reporting Service Manager controlan automáticamente los campos de encabezado de solicitud comunes, lo que le permite especificar las propiedades Authentication, CustomerId, AccountId y DeveloperToken en el objeto AuthorizationData una vez para cada servicio.

Nota:

BulkServiceManager y ReportingServiceManager están disponibles con los SDK de .NET, Java y Python.

El siguiente bloque de código muestra cómo crear una instancia de AuthorizationData y establecer sus propiedades Authentication, CustomerId, AccountId y DeveloperToken .

var authorizationData = new AuthorizationData
{
    Authentication = <AuthenticationGoesHere>, 
    CustomerId = <CustomerIdGoesHere>,
    AccountId = <AccountIdGoesHere>,
    DeveloperToken = "<DeveloperTokenGoesHere>"
};

static AuthorizationData authorizationData = new AuthorizationData();
authorizationData.setAuthentication(<AuthenticationGoesHere>);
authorizationData.setCustomerId("<CustomerIdGoesHere>");
authorizationData.setAccountId("<AccountIdGoesHere>");
authorizationData.setDeveloperToken("<DeveloperTokenGoesHere>");

$authorizationData = (new AuthorizationData())
    ->withAuthentication($AuthenticationGoesHere)
    ->withCustomerId($CustomerIdGoesHere)
    ->withAccountId($AccountIdGoesHere)
    ->withDeveloperToken($DeveloperTokenGoesHere);

authorization_data = AuthorizationData(
    authentication = <AuthenticationGoesHere>,
    customer_id = <CustomerIdGoesHere>,
    account_id = <AccountIdGoesHere>,
    developer_token = '<DeveloperTokenGoesHere>'
)

La propiedad Authentication debe establecerse en una clase derivada de Authentication, como OAuthWebAuthCodeGrant, OAuthDesktopMobileAuthCodeGrant o OAuthDesktopMobileImplicitGrant.

Algunos servicios como Customer Management no aceptan encabezados CustomerId y CustomerAccountId , por lo que se omitirán si los especificó en el objeto AuthorizationData .

Uso del cliente de servicio

Puede usar una instancia de la clase ServiceClient para llamar a cualquier método de uno de los servicios web de Microsoft Advertising. La clase ServiceClient controla automáticamente los campos de encabezado de solicitud comunes, lo que permite especificar las propiedades Authentication, CustomerId, AccountId y DeveloperToken en el objeto AuthorizationData una vez para cada servicio.

Sugerencia

Si usa Bulk o Reporting Services, use la Service Manager masiva o informes Service Manager en lugar de ServiceClient. Por ejemplo, la Service Manager masiva enviará la solicitud de descarga al servicio en masa, sondeará el servicio hasta que se complete y descargará el archivo en el directorio local que especificó en la solicitud. Ahorrará aún más tiempo porque no tiene que escribir ni analizar los archivos de carga o de resultados.

// The primary method of the ServiceClient class is CallAsync. The method parameter is the delegate 
// for the service operation that you want to call. The request parameter of this method must be a 
// request message corresponding to the name of the service operation specified by the first request parameter. 
// The request message must match the service operation that is specified as the delegate in the first request.

public async Task<TResponse> CallAsync<TRequest, TResponse>(
    Func<TService, TRequest, Task<TResponse>> method, TRequest request)

// In the following sample, the method delegate is (s, r) => s.GetUserAsync(r) which takes a GetUserRequest 
// message as the request parameter (TRequest) and returns a GetUserResponse message (TResponse).

private async Task<User> GetUserAsync(long? userId)
{
    var request = new GetUserRequest
    {
        UserId = userId
    };

    return (await _customerService.CallAsync((s, r) => s.GetUserAsync(r), request)).User;
}

// You can use the Customer Management service to get the current authenticated user.

ServiceClient<ICustomerManagementService> CustomerService = new ServiceClient<ICustomerManagementService>(
		authorizationData, 
		ICustomerManagementService.class);

java.lang.Long userId = null;
final GetUserRequest getUserRequest = new GetUserRequest();
getUserRequest.setUserId(userId);

// If you updated the authorization data such as account ID or you want to call a new operation, 
// you must call getService to set the latest request headers. 
// As a best practice you should use getService when calling any service operation.
User user = CustomerService.getService().getUser(getUserRequest).getUser();

// You can use a single instance of the ServiceClient class to call any methods in the service, 
// for example you can set the CustomerManagementVersion13 service client type as follows.

$customerProxy = new ServiceClient(ServiceClientType::CustomerManagementVersion13, $authorizationData, ApiEnvironment::Sandbox);
)

# You can use the Customer Management service to get the current authenticated user.

customer_service = ServiceClient(
    'CustomerManagementService', 
    version = 13,
    authorization_data=authorization_data, 
    environment = ENVIRONMENT,
)

user = customer_service.GetUser(UserId = None).User

Importante

Si establece los elementos de encabezado AuthenticationToken, CustomerId, AccountId o DeveloperToken en el parámetro de solicitud, por ejemplo, GetUserRequest, se omitirán. El cliente de servicio siempre usa authorizationdata proporcionado con su inicialización.

Consulta también

Espacio aislado
Ejemplos de código de api de Bing Ads
Direcciones del servicio web de la API de Bing Ads