Sprache

Authentifizierung mit den SDKs

In diesem Artikel werden Authentifizierungs- und Basisdienstaufrufe 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 Bulk Dienst-Manager-, Service Client- und Reporting Dienst-Manager-Instanzen festlegen. Durch das Festlegen der apiEnvironment wird die globale Einstellung nur für die angegebene Dienstclient-Instance oder -Instanzen außer Kraft gesetzt. Sofern nicht anders beabsichtigt, 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 OAuth 2.0-Standardfluss, wie im The OAuth 2.0 Authorization Framework ausführlich definiert. Die OAuth-Klassen im SDK abstrahieren die Details der Benutzerberechtigung auf niedriger Ebene, z. B. das Formatieren der Autorisierungs- und Umleitungs-URIs, das Festlegen der Anforderungsheader und das Analysieren des Umleitungsverkehrs und des Antwortstroms. Um OAuth mit dem Bing Ads .NET SDK verwenden zu können, muss die Authentication-Eigenschaft Ihres AuthorizationData-Objekts auf eine von der Authentifizierung abgeleitete Klasse festgelegt werden, z. B. OAuthWebAuthCodeGrant, OAuthDesktopMobileAuthCodeGrant oder OAuthDesktopMobileImplicitGrant.

Für die wiederholte oder langfristige Authentifizierung sollten Sie den Autorisierungscodegewährungsprozess zum Abrufen eines Zugriffstokens befolgen. Die folgenden Schritte folgen dem Autorisierungscode-Erteilungsfluss. Weitere Informationen zum Registrieren einer Anwendung und zum Autorisierungscodegewährungsfluss 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 die Client-ID (registrierte Anwendungs-ID), den geheimen Clientschlüssel (registriertes Kennwort) und den 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 Zustimmung des Benutzers an, indem Sie über ein Webbrowser-Steuerelement eine Verbindung mit dem Autorisierungsendpunkt des Microsoft-Kontos herstellen. Rufen Sie die GetAuthorizationEndpoint-Methode der OAuthWebAuthCodeGrant-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 Webbrowser-Steuerelement zur Microsoft-Kontoautorisierung aufgefordert, Ihrer Anwendung Berechtigungen zur Verwaltung seiner Microsoft Advertising-Konten zu erteilen.

    Der Autorisierungsdienst ruft Ihre Anwendung mit dem Umleitungs-URI zurück, der einen Autorisierungscode enthält, falls der Benutzer Ihre Anwendung zur Verwaltung seiner Microsoft Advertising-Konten autorisiert hat. Der 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 anzufordern und das Token zu aktualisieren. Übergeben Sie den vollständigen Rückruf-URI, wenn Sie die OAuthWebAuthCodeGrant-instance verwenden, um das Zugriffstoken anzufordern und das Token zu aktualisieren.

    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. Um Bing Ads API-Dienstvorgänge aufzurufen, sollten Sie entweder Service Client, Bulk Dienst-Manager oder Reporting Dienst-Manager mit AuthorizationData initialisieren, der Ihre OAuthWebAuthCodeGrant-Instance enthält.

    Weitere Informationen finden Sie unter Verwenden von AuthorizationData, Verwenden von Service Client, 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 Service Client, Bulk Dienst-Manager oder Reporting Dienst-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 gültig sein. Unabhängig davon sollten Sie erneut bei Schritt 1 beginnen und die Zustimmung des Benutzers anfordern, wenn beispielsweise der Benutzer des Microsoft-Kontos sein Kennwort geändert, ein Gerät aus seiner Liste der vertrauenswürdigen Geräte entfernt oder die Berechtigungen für Ihre Anwendung zur Authentifizierung in seinem Namen entfernt hat.

Verwenden von AuthorizationData

Die AuthorizationData-Klasse enthält Eigenschaften, die Microsoft Advertising verwendet, um einen Benutzer zu autorisieren. Die Klassen Service Client, Bulk Dienst-Manager und Reporting Dienst-Manager verarbeiten allgemeine Anforderungsheaderfelder für Sie, sodass Sie die Eigenschaften Authentication, CustomerId, AccountId und DeveloperToken im AuthorizationData-Objekt einmal für jeden Dienst 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 ihre 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 festgelegt werden, z. B. OAuthWebAuthCodeGrant, OAuthDesktopMobileAuthCodeGrant oder OAuthDesktopMobileImplicitGrant.

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

Dienstclient verwenden

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 Sie die Eigenschaften Authentication, CustomerId, AccountId und DeveloperToken im AuthorizationData-Objekt einmal für jeden Dienst angeben können.

Tipp

Wenn Sie die Massen- oder Berichtsdienste verwenden, verwenden Sie den Massen-Dienst-Manager oder den Reporting Dienst-Manager anstelle von ServiceClient. Beispielsweise sendet der Bulk Dienst-Manager Ihre Downloadanforderung an den Massendienst, fragt 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 AuthenticationToken-, CustomerId-, AccountId- oder DeveloperToken-Headerelemente im Anforderungsparameter festlegen, z. B. GetUserRequest, werden sie ignoriert. Service Client verwendet immer die AuthorizationData, die bei der Initialisierung bereitgestellt werden.

Hier ist eine an Microsoft angepasste, klarheitsoptimierte, barrierefreie Revision Ihrer Markdown-Inhalte.
Ich habe die Anleitung aus Ihren Stilressourcen angewendet – einschließlich Satzschreibung, Scanbarkeit, prägnante Schritte und Copilot-freundliche Struktur. [Anleitung zur Eingabeaufforderung | Word], [AI agent k... Simssockel | Word]

Google Login Support

Ab Bing Ads SDK Version 13.0.26 können Sie sich mit Ihrem Google-Konto bei Microsoft Advertising anmelden, anstatt ein Microsoft-Konto zu erstellen.

Das SDK enthält zwei Klassen für die Google-Authentifizierung:

  • GoogleOAuthDesktopMobileAuthCodeGrant
  • GoogleOAuthWebAuthCodeGrant

Diese funktionieren ähnlich wie die vorhandenen OAuth-Code-Gewährungsklassen für Desktop-, Mobil- und Web-Apps.

Wichtige Hinweise:

  • Beide Google OAuth-Klassen erfordern einen geheimen Clientschlüssel. Die Standardklasse OAuthDesktopMobileAuthCodeGrant tut dies nicht.
  • Wenn Sie ein Zugriffstoken mit einem Google-Aktualisierungstoken aktualisieren, gibt Google kein neues Aktualisierungstoken zurück. Das ursprüngliche Aktualisierungstoken bleibt gültig, bis es abläuft oder widerrufen wird.

So autorisieren Sie sich mit Google

1. Berechtigungsobjekt anlegen

Erstellen Sie eine Instance, um die GoogleOAuthWebAuthCodeGrant Google-Kontoautorisierung zu verwalten.

Ersetzen Sie die Client-ID, den geheimen Clientschlüssel und den Umleitungs-URI durch die Werte aus Ihrer registrierten Anwendung.

var googleOAuthWebAuthCodeGrant =
    new GoogleOAuthWebAuthCodeGrant(ClientId, ClientSecret, new Uri(RedirectionUri), ApiEnvironment);

// Provide a non‑guessable state parameter to help prevent CSRF attacks.
googleOAuthWebAuthCodeGrant.State = "ClientStateGoesHere";

Leiten Sie den Benutzer zum Google-Autorisierungsendpunkt um, indem GetAuthorizationEndpoint()Sie .

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

Der Benutzer wird aufgefordert, Ihrer App die Berechtigung zur Verwaltung seiner Microsoft Advertising-Konten zu erteilen.
Nach der Einwilligung ruft Google Ihre Weiterleitungs-URI mit einem Autorisierungscode auf.

Beispiel für Rückruf:

https://contoso.com/redirect/?code=CODE&scope=email+profile+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email+openid&authuser=0&prompt=consent

Verwenden Sie den Autorisierungscode sofort im nächsten Schritt.

3. Tauschen Sie den Autorisierungscode gegen Token aus.

Übergeben Sie den vollständigen Rückruf-URI , um die Zugriffs- und Aktualisierungstoken anzufordern.

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

Nach diesem Schritt kann Ihre App die Microsoft Advertising-Konten des Benutzers verwalten.

4. Aktualisieren des Zugriffstokens

Verwenden Sie das Aktualisierungstoken, wenn das Zugriffstoken abläuft.

// Use an existing refresh token to request new access tokens.
if (GetRefreshToken(out refreshToken))
{
    googleOAuthWebAuthCodeGrant.RequestAccessAndRefreshTokensAsync(refreshToken);
}

Siehe auch

Sandbox
Bing Ads API-Codebeispiele
Bing Ads API-Webdienstadressen

  • Zuletzt aktualisiert um