Introducción a Bing Ads API

  • Artículo

Cualquier usuario de Microsoft Advertising con un token de desarrollador puede empezar a usar bing ads API. Para los anunciantes que colocan un gran número de anuncios o desarrolladores que crean herramientas de publicidad, bing Ads API proporciona una interfaz de programación a Microsoft Advertising.

Puede desarrollar la aplicación de API de Bing Ads en cualquier idioma que admita servicios web. Para empezar a trabajar con un SDK específico, consulte Introducción aPythonPHP | de C# | Java | .

Obtención de un token de acceso de usuario

Considere el usuario que desea iniciar sesión, por ejemplo, example@contoso.com. Bing Ads API no aceptará esa dirección de correo electrónico y contraseña. En su lugar, debe establecer el elemento de encabezado AuthenticationToken que contiene un token de acceso de usuario. Puede pensar que un token de acceso representa un nombre de usuario y una contraseña.

¿Cómo puede obtener un token de acceso para un usuario? Como desarrollador de aplicaciones, usará una dirección URL de autorización de Microsoft para pedir consentimiento al usuario de Microsoft Advertising. Una vez que un usuario proporciona consentimiento, puede obtener un token de acceso y actuar en nombre del usuario. El token de acceso representa las credenciales de usuario que tienen acceso a una o varias cuentas de Microsoft Advertising.

  1. Registro de una aplicación

  2. Solicitar el consentimiento del usuario para que la aplicación administre sus cuentas de Microsoft Advertising

  3. Obtención de tokens de acceso y actualización

  4. Realización de la primera llamada API

Sugerencia

Para obtener más información sobre cómo obtener acceso y actualizar tokens mediante los SDK de Bing Ads, consulte Autenticación con los SDK.

Obtención de un token de desarrollador

Para usar las API de Bing Ads, debe tener un token de desarrollador y credenciales de usuario válidas. Si aún no tiene una cuenta de Microsoft Advertising, puede registrarse a través de la aplicación web de Microsoft Advertising.

Nota:

Los entornos de espacio aislado y producción usan credenciales independientes. Puede registrarse para obtener una cuenta de espacio aisladoaquí. Todos pueden usar el token de desarrollador de espacio aislado universal, es decir, BBD37VB98.

Puede seguir estos pasos para obtener un token de desarrollador para producción.

  1. Inicie sesión con las credenciales de Super Administración en la pestaña de la cuenta del Portal para desarrolladores de Microsoft Advertising.
  2. Elija el usuario que desea asociar con el token de desarrollador. Normalmente, una aplicación solo necesita un token universal independientemente del número de usuarios que se admitirán.
  3. Haga clic en el botón Solicitar token .

El token de desarrollador universal se puede usar para autenticarse con cualquier credencial de usuario de Microsoft Advertising. Puede usar el mismo token de desarrollador universal si uno o varios usuarios de Microsoft Advertising usarán la aplicación. A partir de julio de 2019, este es el tipo de token predeterminado.

El token de desarrollador de un solo usuario solo se puede usar para autenticar a un usuario para acceder a un cliente. Este tipo de token ha quedado en desuso en favor del token universal. Si sigue viendo que se asigna un solo token de usuario a uno de los usuarios, puede seleccionar "Actualizar a universal".

Un token de desarrollador permite el acceso mediante programación a las cuentas permitidas para un usuario. La obtención de un token de desarrollador para el acceso a la API no concede permisos adicionales a ninguna cuenta de Microsoft Advertising. A cada usuario de Microsoft Advertising se le asigna un rol, por ejemplo, Super Administración o Administrador de campañas de anunciantes para cada cliente al que pueda acceder. Con un token de desarrollador, las mismas cuentas disponibles en la aplicación web de Microsoft Advertising están disponibles para el usuario mediante programación a través de la API.

Dónde usar las credenciales de API

Al llamar a una operación de servicio como GetCampaignsByAccountId, debe especificar elementos de encabezado de solicitud como DeveloperToken, CustomerId y CustomerAccountId.

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

Si usa uno de los SDK de Microsoft Advertising, los elementos de encabezado de solicitud se establecen mediante AuthorizationData. Para obtener más información sobre la biblioteca de autenticación del SDK, consulte Autenticación con los SDK.

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

Obtención de su cuenta e identificadores de cliente

Para obtener el identificador de cliente y el identificador de cuenta de un usuario, puede iniciar sesión en la aplicación web de Microsoft Advertising y hacer clic en la pestaña Campañas . La dirección URL contendrá un par clave-valor cid en la cadena de consulta que identifica el identificador de cliente y un par clave-valor de ayuda que identifica el identificador de cuenta. Por ejemplo, https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere& aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign.

Sugerencia

No confunda el número de cuenta con el identificador de cuenta. El número de cuenta es el número de cuenta generado por el sistema que se usa para identificar la cuenta en la aplicación web de Microsoft Advertising. El número de cuenta tiene el formato xxxxxxxx, donde xxxxxxxx es una serie de ocho caracteres alfanuméricos. Las solicitudes de servicio de API solo usan el identificador de cuenta y nunca usan el número de cuenta.

Con la API de administración de clientes, puede obtener los identificadores de cliente y cuenta para cada usuario autenticado.

Llame a GetUser con sus credenciales de Microsoft Advertising y DeveloperToken. Dentro del objeto Body, establezca el valor de UserId nil. La respuesta incluirá un objeto User que contiene el UserId.

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

A continuación, llame a SearchAccounts con el UserId devuelto a través del paso anterior. La cuenta de anunciante devuelta (o cuentas) incluirá los identificadores de cuenta y cliente.

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

Sugerencia

Consulte Ejemplo de código de cuentas de usuario de búsqueda para obtener un ejemplo de código que devuelva cuentas para el usuario autenticado actual.

Referencia de elementos de encabezado

Las operaciones del servicio API de Bing Ads usan el Protocolo simple de acceso a objetos (SOAP) para intercambiar los mensajes de solicitud y respuesta con la operación de servicio. Para obtener más información, consulte Protocolo de servicios de API de Bing Ads.

Cada solicitud SOAP debe incluir los siguientes encabezados SOAP, que contienen las credenciales del usuario.

Nota:

Los elementos CustomerAccountId y CustomerId no son aplicables a los servicios customer billing y customer management.

Elemento Descripción Tipo de datos
ApplicationToken Este elemento de encabezado no se usa y se debe omitir. string
AuthenticationToken Token de acceso de OAuth que representa a un usuario de la cuenta Microsoft que tiene permisos para cuentas de Microsoft Advertising. Para obtener más información, consulte Autenticación con OAuth. string
CustomerAccountId Identificador de la cuenta propietaria de las entidades de la solicitud. Este elemento de encabezado debe tener el mismo valor que el elemento de cuerpo AccountId cuando ambos son necesarios. Este elemento es necesario para la mayoría de las operaciones de servicio y, como procedimiento recomendado, siempre debe establecerlo. string
Customerid Identificador del cliente que contiene y posee la cuenta. Si administra una cuenta de otro cliente, debe usar ese identificador de cliente en lugar de su propio identificador de cliente. Este elemento es necesario para la mayoría de las operaciones de servicio y, como procedimiento recomendado, siempre debe establecerlo. string
DeveloperToken Token de desarrollador que se usa para acceder a Bing Ads API. string
Password Este elemento está reservado para uso interno y se quitará de una versión futura de la API. Debe usar el elemento AuthenticationToken para establecer las credenciales de usuario. string
UserName Este elemento está reservado para uso interno y se quitará de una versión futura de la API. Debe usar el elemento AuthenticationToken para establecer las credenciales de usuario. string

¿Necesita ayuda?

Para obtener sugerencias de solución de problemas, consulte Control de errores y excepciones del servicio.

El foro microsoft Q&A está disponible para que la comunidad de desarrolladores formule y responda preguntas sobre las API de Bing Ads y los scripts de Microsoft Advertising. Microsoft supervisa los foros y las respuestas a las preguntas que la comunidad aún no ha respondido.

Importante

Para asegurarse de que vemos su pregunta, etiquete esta opción con "advertising-api".

Si la investigación implica información confidencial de la cuenta o los datos personales, o si no encuentra la información que necesita para resolver el problema a través de Microsoft Q&A, póngase en contacto con el Soporte técnico de Microsoft Advertising. Para resolver el problema de forma eficaz, proporcione soporte técnico con los detalles solicitados en Soporte técnico de participación.

Consulta también

Introducción a la API de Bing Ads
Conceptos de api de Bing Ads