Erste Schritte mit der Bing Ads-API
Jeder Microsoft Advertising-Benutzer mit einem Entwicklertoken kann mit der Verwendung der Bing Ads-API beginnen. Für Werbetreibende, die eine große Anzahl von Anzeigen schalten, oder Entwickler, die Werbetools erstellen, bietet die Bing Ads-API eine programmgesteuerte Schnittstelle zu Microsoft Advertising.
Sie können Ihre Bing Ads-API-Anwendung in jeder Sprache entwickeln, die Webdienste unterstützt. Informationen zu den ersten Schritten mit einem bestimmten SDK finden Sie unter Erste Schritte in C# | Java | PHP | Python.
Abrufen eines Benutzerzugriffstokens
Betrachten Sie den Benutzer, den Sie anmelden möchten, example@contoso.comz. B. . Die Bing Ads-API akzeptiert diese E-Mail-Adresse und das Kennwort nicht. Stattdessen müssen Sie das AuthenticationToken-Headerelement festlegen, das ein Benutzerzugriffstoken enthält. Sie können sich ein Zugriffstoken vorstellen, das einen Benutzernamen und ein Kennwort darstellt.
Wie können Sie ein Zugriffstoken für einen Benutzer erhalten? Als Anwendungsentwickler verwenden Sie eine Microsoft-Autorisierungs-URL, um den Microsoft Advertising-Benutzer zur Zustimmung aufzufordern. Sobald ein Benutzer seine Zustimmung erteilt hat, können Sie ein Zugriffstoken abrufen und im Namen des Benutzers handeln. Das Zugriffstoken stellt die Benutzeranmeldeinformationen dar, die Zugriff auf ein oder mehrere Microsoft Advertising-Konten haben.
Anfordern der Benutzerzustimmung für Ihre Anwendung zur Verwaltung ihrer Microsoft Advertising-Konten
Tipp
Ausführliche Informationen zum Abrufen von Zugriffs- und Aktualisierungstoken mithilfe der Bing Ads SDKs finden Sie unter Authentifizierung mit den SDKs.
Abrufen eines Entwicklertokens
Um Bing Ads-APIs verwenden zu können, benötigen Sie ein Entwicklertoken und gültige Benutzeranmeldeinformationen. Wenn Sie noch nicht über ein Microsoft Advertising-Konto verfügen, können Sie sich über die Microsoft Advertising-Webanwendung registrieren.
Hinweis
Die Sandbox- und Produktionsumgebungen verwenden separate Anmeldeinformationen. Sie können sich hier für ein Sandbox-Konto registrieren. Jeder kann das universelle Sandbox-Entwicklertoken verwenden, d. h. BBD37VB98.
Sie können diese Schritte ausführen, um ein Entwicklertoken für die Produktion abzurufen.
- Melden Sie sich mit den Anmeldeinformationen von Super Admin auf der Registerkarte Microsoft Advertising Developer Portal-Konto an.
- Wählen Sie den Benutzer aus, der dem Entwicklertoken zugeordnet werden soll. In der Regel benötigt eine Anwendung nur ein universelles Token, unabhängig davon, wie viele Benutzer unterstützt werden.
- Klicken Sie auf die Schaltfläche Token anfordern .
Das universelle Entwicklertoken kann für die Authentifizierung mit allen Microsoft Advertising-Benutzeranmeldeinformationen verwendet werden. Sie können dasselbe universelle Entwicklertoken verwenden, unabhängig davon, ob Ihre Anwendung von einem oder mehreren Microsoft Advertising-Benutzern verwendet wird. Ab Juli 2019 ist dies der Standardtokentyp.
Das Einzelbenutzer-Entwicklertoken kann nur verwendet werden, um einen Benutzer für den Zugriff auf einen Kunden zu authentifizieren. Dieser Tokentyp wurde zugunsten des universellen Tokens als veraltet gekennzeichnet. Wenn Sie immer noch sehen, dass einem Ihrer Benutzer ein einzelnes Benutzertoken zugewiesen ist, können Sie "Upgrade to Universal" auswählen.
Ein Entwicklertoken ermöglicht den programmgesteuerten Zugriff auf die Konten, die einem Benutzer erlaubt sind. Durch das Abrufen eines Entwicklertokens für den API-Zugriff werden keine zusätzlichen Berechtigungen für Microsoft Advertising-Konten gewährt. Jedem Microsoft Advertising-Benutzer wird eine Rolle zugewiesen, z. B. Super Admin oder Advertiser Campaign Manager für jeden Kunden, auf den er zugreifen kann. Mit einem Entwicklertoken stehen dem Benutzer die gleichen Konten, die in der Microsoft Advertising-Webanwendung verfügbar sind, programmgesteuert über die API zur Verfügung.
Verwenden der API-Anmeldeinformationen
Wenn Sie einen Dienstvorgang wie GetCampaignsByAccountId aufrufen, müssen Sie Anforderungsheaderelemente wie DeveloperToken, CustomerId und CustomerAccountId angeben.
<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<Action mustUnderstand="1">GetCampaignsByAccountId</Action>
<ApplicationToken i:nil="false">ValueHere</ApplicationToken>
<AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
<CustomerAccountId i:nil="false">ValueHere</CustomerAccountId>
<CustomerId i:nil="false">ValueHere</CustomerId>
<DeveloperToken i:nil="false">ValueHere</DeveloperToken>
</s:Header>
<s:Body>
<GetCampaignsByAccountIdRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<AccountId>ValueHere</AccountId>
<CampaignType>ValueHere</CampaignType>
</GetCampaignsByAccountIdRequest>
</s:Body>
</s:Envelope>
Wenn Sie eines der Microsoft Advertising SDKs verwenden, werden die Anforderungsheaderelemente mithilfe von AuthorizationData festgelegt. Weitere Informationen zur SDK-Authentifizierungsbibliothek finden Sie unter Authentifizierung mit den SDKs.
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>'
)
Abrufen Ihrer Konto- und Kunden-IDs
Um die Kunden-ID und konto-ID eines Benutzers abzurufen, können Sie sich bei der Microsoft Advertising-Webanwendung anmelden und auf die Registerkarte Kampagnen klicken. Die URL enthält ein CID-Schlüssel-Wert-Paar in der Abfragezeichenfolge, das Ihre Kunden-ID identifiziert, und ein Hilfsschlüssel-Wert-Paar, das Ihre Konto-ID identifiziert. Beispiel: https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere& aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign.
Tipp
Verwechseln Sie die Kontonummer nicht mit dem Kontobezeichner. Die Kontonummer ist die vom System generierte Kontonummer, die zum Identifizieren des Kontos in der Microsoft Advertising-Webanwendung verwendet wird. Die Kontonummer hat das Format xxxxxxxx, wobei xxxxxxxx eine Reihe von acht beliebigen alphanumerischen Zeichen ist. Die API-Dienstanforderungen verwenden nur den Kontobezeichner und nie die Kontonummer.
Mit der Kundenverwaltungs-API können Sie die Kunden- und Konto-IDs für jeden authentifizierten Benutzer abrufen.
Rufen Sie GetUser mit Ihren Microsoft Advertising-Anmeldeinformationen und DeveloperToken auf. Legen Sie innerhalb des Textkörpers die UserId null fest. Die Antwort enthält ein User-Objekt , das die UserId enthält.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
<h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
<h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
</s:Header>
<s:Body>
<GetUserRequest xmlns="https://bingads.microsoft.com/Customer/v13">
<UserId i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
</GetUserRequest>
</s:Body>
</s:Envelope>
Rufen Sie dann SearchAccounts mit der UserId auf, die im vorherigen Schritt zurückgegeben wurde. Das zurückgegebene Werbekundenkonto (oder -konten) enthält Konto- und Kundenbezeichner.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
<h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
<h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
</s:Header>
<s:Body>
<SearchAccountsRequest xmlns="https://bingads.microsoft.com/Customer/v13">
<Predicates xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Predicate>
<a:Field>UserId</a:Field>
<a:Operator>Equals</a:Operator>
<a:Value>UserIdGoesHere</a:Value>
</a:Predicate>
</Predicates>
<Ordering i:nil="true" xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
<PageInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Index>0</a:Index>
<a:Size>10</a:Size>
</PageInfo>
</SearchAccountsRequest>
</s:Body>
</s:Envelope>
Tipp
Ein Codebeispiel, das Konten für den aktuellen authentifizierten Benutzer zurückgibt, finden Sie unter Codebeispiel für Die Suche nach Benutzerkonten .
Referenz zu Headerelementen
Bing Ads-API-Dienstvorgänge verwenden SOAP (Simple Object Access Protocol), um die Anforderungs- und Antwortnachrichten mit dem Dienstvorgang auszutauschen. Weitere Informationen finden Sie unter Bing Ads API Services Protocol.
Jede SOAP-Anforderung muss die folgenden SOAP-Header enthalten, die die Anmeldeinformationen des Benutzers enthalten.
Hinweis
Die Elemente CustomerAccountId und CustomerId gelten nicht für die Dienste Customer Billing und Customer Management.
| Element | Beschreibung | Datentyp |
|---|---|---|
| ApplicationToken | Dieses Headerelement wird nicht verwendet und sollte ignoriert werden. | Zeichenfolge |
| AuthenticationToken | Das OAuth-Zugriffstoken, das einen Microsoft-Kontobenutzer darstellt, der über Berechtigungen für Microsoft Advertising-Konten verfügt. Weitere Informationen finden Sie unter Authentifizierung mit OAuth. | Zeichenfolge |
| CustomerAccountId | Der Bezeichner des Kontos, das die Entitäten in der Anforderung besitzt. Dieses Headerelement muss denselben Wert wie das AccountId-Body-Element aufweisen, wenn beides erforderlich ist. Dieses Element ist für die meisten Dienstvorgänge erforderlich, und als bewährte Methode sollten Sie es immer festlegen. | Zeichenfolge |
| Customerid | Der Bezeichner des Kunden, der das Konto enthält und besitzt. Wenn Sie ein Konto eines anderen Kunden verwalten, sollten Sie diese Kunden-ID anstelle Ihrer eigenen Kunden-ID verwenden. Dieses Element ist für die meisten Dienstvorgänge erforderlich, und als bewährte Methode sollten Sie es immer festlegen. | Zeichenfolge |
| DeveloperToken | Das Entwicklertoken, das für den Zugriff auf die Bing Ads-API verwendet wird. | Zeichenfolge |
| Kennwort | Dieses Element ist für die interne Verwendung reserviert und wird aus einer zukünftigen Version der API entfernt. Sie müssen das AuthenticationToken-Element verwenden, um Benutzeranmeldeinformationen festzulegen. | Zeichenfolge |
| UserName | Dieses Element ist für die interne Verwendung reserviert und wird aus einer zukünftigen Version der API entfernt. Sie müssen das AuthenticationToken-Element verwenden, um Benutzeranmeldeinformationen festzulegen. | Zeichenfolge |
Benötigen Sie Hilfe?
Tipps zur Problembehandlung finden Sie unter Behandeln von Dienstfehlern und Ausnahmen.
Das Microsoft Q&A-Forum steht der Entwicklercommunity zur Verfügung, um Fragen zu den Bing Ads-APIs und Microsoft Advertising-Skripts zu stellen und zu beantworten. Microsoft überwacht die Foren und beantwortet Fragen, die die Community noch nicht beantwortet hat.
Wichtig
Um sicherzustellen, dass Ihre Frage angezeigt wird, markieren Sie sie mit "advertising-api".
Wenn die Untersuchung sensible Konten oder persönliche Daten umfasst oder Wenn Sie die informationen, die Sie benötigen, um Ihr Problem über Microsoft Q&A zu lösen, nicht finden, wenden Sie sich an den Microsoft Advertising-Support. Um das Problem effizient zu beheben, stellen Sie Support mit den unter Einbinden des Supports angeforderten Details bereit.