Share via

Authentifizierung mit den SDKs

  • Artikel

In diesem Artikel werden die Authentifizierung und grundlegende Dienstaufrufe mit den Bing Ads SDKs behandelt.

Konfigurieren der Sandbox

Das SDK verwendet standardmäßig die Produktionsumgebung. Mit den .NET- und Java-SDKs können Sie es in eine Sandbox mit einer globalen Konfiguration ändern. Während die globale Konfiguration mit PHP- und Python-SDKs nicht verfügbar ist, können Sie eine globale Konfiguration oder eine andere benutzerdefinierte Lösung erstellen.

// 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

Sie können auch den API-Umgebungsparameter einzelner Massen-Service Manager-, Dienstclient- und Reporting-Service Manager-Instanzen festlegen. Durch festlegen von apiEnvironment wird die globale Einstellung nur für den angegebenen Dienstclient instance oder Instanzen außer Kraft gesetzt. Sofern nicht anders vorgesehen, sollten Sie darauf achten, nicht versehentlich eine gemischte Gruppe von Umgebungen zu konfigurieren.

Hinweis

BulkServiceManager und ReportingServiceManager sind mit den .NET-, Java- und Python-SDKs verfügbar.

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',
)

Verwenden von OAuth

Bing Ads SDKs unterstützen den standardmäßigen OAuth 2.0-Flow, der im OAuth 2.0-Autorisierungsframework ausführlich definiert ist. Die OAuth-Klassen im SDK abstrahieren die Details zur Benutzerautorisierung auf niedriger Ebene, z. B. das Formatieren der Autorisierungs- und Umleitungs-URIs, das Festlegen der Anforderungsheader und das Analysieren des Umleitungsdatenverkehrs und des Antwortdatenstroms. Um OAuth mit dem Bing Ads .NET SDK zu verwenden, muss die Authentication-Eigenschaft Ihres AuthorizationData-Objekts auf eine von Authentifizierung abgeleitete Klasse wie OAuthWebAuthCodeGrant, OAuthDesktopMobileAuthCodeGrant oder OAuthDesktopMobileImplicitGrant festgelegt werden.

Für die wiederholte oder langfristige Authentifizierung sollten Sie den Autorisierungscodegenehmigungsflow befolgen, um ein Zugriffstoken abzurufen. Die folgenden Schritte folgen dem Autorisierungscode-Genehmigungsflow. Weitere Informationen zum Registrieren einer Anwendung und zum Autorisierungscodegenehmigungsflow finden Sie unter Authentifizierung mit OAuth.

  1. Erstellen Sie eine instance von OAuthWebAuthCodeGrant, die zum Verwalten der Benutzerautorisierung des Microsoft-Kontos verwendet wird. Ersetzen Sie Client-ID (registrierte Anwendungs-ID), geheimer Clientschlüssel (registriertes Kennwort) und Umleitungs-URI durch die Werte, die bei der Registrierung Ihrer Anwendung konfiguriert wurden.

    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. Fordern Sie die Benutzereinwilligung an, indem Sie über ein Webbrowsersteuerelement eine Verbindung mit dem Autorisierungsendpunkt des Microsoft-Kontos herstellen. Rufen Sie die GetAuthorizationEndpoint-Methode der OAuthWebAuthAuthCodeGrant-instance auf, die Sie im vorherigen Schritt erstellt haben.

    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()

    Der Benutzer wird über das Webbrowsersteuerelement für die Microsoft-Kontoautorisierung aufgefordert, Ihrer Anwendung Berechtigungen zum Verwalten seiner Microsoft Advertising-Konten zu erteilen.

    Der Autorisierungsdienst ruft ihre Anwendung mit dem Umleitungs-URI zurück, der einen Autorisierungscode enthält, wenn der Benutzer Ihre Anwendung zum Verwalten seiner Microsoft Advertising-Konten autorisiert hat. Die Rückruf-URL enthält beispielsweise einen Autorisierungscode wie folgt, wenn der Benutzer Ihrer Anwendung Berechtigungen zum Verwalten seiner Microsoft Advertising-Konten erteilt hat: https://contoso.com/redirect/?code=CODE& state=ClientStateGoesHere. Wenn der Benutzer Ihrer Anwendung Berechtigungen zum Verwalten seiner Microsoft Advertising-Konten erteilt hat, sollten Sie den Code sofort im nächsten Schritt verwenden. Die kurze Dauer des Autorisierungscodes( ca. 5 Minuten) kann sich ändern.

    Wenn der Benutzer Ihre Anwendungsberechtigungen zum Verwalten seiner Microsoft Advertising-Konten verweigert hat, enthält der Rückruf-URI ein Fehler- und Fehlerbeschreibungsfeld wie folgt: REDIRECTURI?error=access_denied&error_description=ERROR_DESCRIPTION&state=ClientStateGoesHere.

  3. Verwenden Sie den Autorisierungscode, um das Zugriffstoken und das Aktualisierungstoken anzufordern. Übergeben Sie den vollständigen Rückruf-URI, wenn Sie die OAuthWebAuthCodeGrant-instance verwenden, um das Zugriffstoken und das Aktualisierungstoken anzufordern.

    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

    Wenn dieser Schritt erfolgreich war, verfügt Ihre Anwendung über Berechtigungen zum Verwalten der Microsoft Advertising-Konten des Benutzers. Zum Aufrufen von Bing Ads-API-Dienstvorgängen sollten Sie entweder Dienstclient, Massen-Service Manager oder Reporting-Service Manager mit AuthorizationData initialisieren, das Ihre OAuthWebAuthCodeGrant-instance enthält.

    Weitere Informationen finden Sie unter Verwenden von AuthorizationData, Verwenden des Dienstclients, Verwenden von BulkServiceManager und Verwenden von ReportingServiceManager.

    Hinweis

    BulkServiceManager und ReportingServiceManager sind mit den .NET-, Java- und Python-SDKs verfügbar.

  4. Beim Aufrufen von Bing Ads-API-Dienstvorgängen mit Dienstclient, Massen-Service Manager oder Reporting Service Manager ist es wichtig, das neueste Aktualisierungstoken zu speichern, wenn neue OAuth-Token empfangen werden.

    // 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)

    Wichtig

    Ein Aktualisierungstoken kann bis zu 90 Tage dauern. Unabhängig davon sollten Sie davon ausgehen, dass Sie von Schritt 1 aus erneut beginnen und die Zustimmung des Benutzers anfordern, wenn der Benutzer des Microsoft-Kontos beispielsweise sein Kennwort geändert, ein Gerät aus der Liste der vertrauenswürdigen Geräte entfernt oder Berechtigungen für die Authentifizierung ihrer Anwendung in ihrem Namen entfernt hat.

Verwenden von AuthorizationData

Die AuthorizationData-Klasse enthält Eigenschaften, die Microsoft Advertising zum Autorisieren eines Benutzers verwendet. Die Klassen Service Client, Bulk Service Manager und Reporting Service Manager verarbeiten allgemeine Anforderungsheaderfelder für Sie, sodass Sie die Eigenschaften Authentication, CustomerId, AccountId und DeveloperToken einmal für jeden Dienst im AuthorizationData-Objekt angeben können.

Hinweis

BulkServiceManager und ReportingServiceManager sind mit den .NET-, Java- und Python-SDKs verfügbar.

Der folgende Codeblock zeigt, wie Sie eine instance von AuthorizationData erstellen und die Eigenschaften Authentication, CustomerId, AccountId und DeveloperToken festlegen.

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>'
)

Die Authentication-Eigenschaft muss auf eine von der Authentifizierung abgeleitete Klasse wie OAuthWebAuthCodeGrant, OAuthDesktopMobileAuthCodeGrant oder OAuthDesktopMobileImplicitGrant festgelegt werden.

Einige Dienste wie die Kundenverwaltung akzeptieren keine CustomerId - und CustomerAccountId-Header , sodass sie ignoriert werden, wenn Sie sie im AuthorizationData-Objekt angegeben haben.

Verwenden des Dienstclients

Sie können eine instance der ServiceClient-Klasse verwenden, um beliebige Methoden eines der Microsoft Advertising-Webdienste aufzurufen. Die ServiceClient-Klasse verarbeitet allgemeine Anforderungsheaderfelder für Sie, sodass die Eigenschaften Authentication, CustomerId, AccountId und DeveloperToken im AuthorizationData-Objekt einmal für jeden Dienst angegeben werden können.

Tipp

Wenn Sie die Bulk- oder Reporting Services verwenden, verwenden Sie anstelle von ServiceClient die Service Manager oder reporting Service Manager. Beispielsweise sendet der Bulk-Service Manager Ihre Downloadanforderung an den Massendienst, ruft den Dienst ab, bis er abgeschlossen ist, und lädt die Datei in das lokale Verzeichnis herunter, das Sie in der Anforderung angegeben haben. Sie sparen noch mehr Zeit, da Sie die Upload- oder Ergebnisdateien nicht schreiben oder analysieren müssen.

// 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

Wichtig

Wenn Sie die Headerelemente AuthenticationToken, CustomerId, AccountId oder DeveloperToken im Anforderungsparameter festlegen, z. B. GetUserRequest, werden diese ignoriert. Der Dienstclient verwendet immer die authorizationData , die bei der Initialisierung bereitgestellt werden.

Siehe auch

Sandbox
Codebeispiele für die Bing Ads-API
Adressen des Bing Ads-API-Webdiensts