Compartir a través de

Descarga y carga masivas

  • Artículo

Con el servicio masivo , puede descargar y cargar la configuración de la campaña de forma asincrónica en segundo plano. El servicio masivo se recomienda para administrar datos a gran escala, especialmente si necesita agregar o actualizar anuncios y palabras clave en varios grupos de anuncios o campañas de una cuenta. Para algunas entidades, también puede descargar sugerencias de puja y datos de puntuación de calidad. Cada registro se puede cargar correctamente independientemente de que otros registros del mismo archivo contengan errores. Para obtener información sobre el esquema usado para el archivo de descarga y carga, incluidos los detalles sobre qué entidades, sugerencias de puja y datos de puntuación de calidad están disponibles, consulte Esquema de archivos masivos.

Importante

Los nuevos tipos de registro (filas) y campos (columnas) se pueden agregar en cualquier momento y no debe depender del orden de registros o campos en el archivo de resultados de carga masiva o descarga masiva. Del mismo modo, a menos que se indique lo contrario en la documentación de referencia, no debe depender de un conjunto fijo de valores devueltos en cada campo.

Si usa un lenguaje .NET, Java o Python, debe usar las bibliotecas de cliente de la API de Bing Ads. Los SDK de .NET, Java y Python abstrae los detalles de bajo nivel que se describen a continuación. Por ejemplo, en lugar de llamar a DownloadCampaignsByAccountIds y GetBulkDownloadStatus para descargar un archivo, puede usar un método con la clase BulkServiceManager . Para obtener más información sobre cómo usar la descarga y carga masivas con los SDK, consulte Service Manager masiva.

Descarga masiva

Para descargar los datos de campaña de una cuenta, llame a la operación DownloadCampaignsByAccountIds . Para descargar los datos de campañas específicas, llame a la operación DownloadCampaignsByCampaignIds .

Descarga de un archivo masivo

Puede solicitar todos los datos de la campaña o solo los datos que han cambiado desde la última vez que descargó los datos de la campaña. Para cualquiera de las operaciones de descarga, a continuación se muestra información general sobre la configuración de la solicitud y el flujo de trabajo de descarga.

Importante

Debe usar las mismas credenciales de usuario para la operación de solicitud de descarga ( DownloadCampaignsByAccountIds o DownloadCampaignsByCampaignIds) y la operación de sondeo GetBulkDownloadStatus .

  1. Establezca el elemento DataScope de la solicitud y especifique si se deben incluir sugerencias de puja o datos de puntuación de calidad además de datos de entidad. Para obtener una lista de los valores posibles, consulte el conjunto de valores DataScope .

  2. Establezca el elemento DownloadFileType de la solicitud para seleccionar Csv o Tsv para el formato del archivo de descarga.

    Nota:

    El archivo Csv o Tsv descargado será comprimido zip o GZIP en función del CompressionType especificado. ZIP es el valor predeterminado si no especificó CompressionType.

  3. Establezca el elemento Entities de la solicitud para incluir las entidades de campaña, grupo de anuncios, anuncio y palabra clave. Opcionalmente, puede incluir entidades adicionales, como palabras clave negativas y destinos, en la descarga. Para obtener una lista de las entidades que puede solicitar, consulte el conjunto de valores DownloadEntity .

  4. Establezca el elemento LastSyncTimeInUTC de la solicitud en la marca de tiempo de la descarga anterior para solicitar solo las entidades que se han actualizado o eliminado desde la última descarga.

    Nota:

    Si es la primera vez que solicita una descarga para las entidades especificadas, establezca el elemento LastSyncTimeInUTC de la solicitud en NULL para descargar todas las entidades disponibles.

  5. Envíe la solicitud de descarga con la operación DownloadCampaignsByAccountIds o DownloadCampaignsByCampaignIds .

  6. La solicitud de descarga devuelve un identificador que se pasa a la operación GetBulkDownloadStatus . Llame a la operación GetBulkDownloadStatus en un bucle hasta que se complete o se produzca un error en la descarga. El tiempo que tarda la descarga en completarse depende de una serie de variables, como el número de campañas que solicitó y el número de solicitudes que ya están en la cola. Debido a estas variables, el intervalo de sondeo que se usa puede variar. Tiene dos días para descargar el archivo desde el momento en que envía la solicitud de descarga. Si no ha descargado correctamente el archivo dentro de este período, se quita del sitio de descarga y tendrá que volver a llamar a una de las operaciones de descarga.

  7. Cuando la operación GetBulkDownloadStatus se completa correctamente, devuelve la dirección URL del archivo de descarga. Use la dirección URL para copiar el archivo de descarga localmente. La dirección URL debe usarse en un plazo de cinco minutos desde el momento en que la operación GetBulkDownloadStatus devuelve un código de estado Success . Si no inicia la descarga dentro de este período de tiempo, tendrá que llamar a GetBulkDownloadStatus de nuevo para obtener una nueva dirección URL.

  8. El archivo de descarga se comprime en formato zip, por lo que debe descomprimir el archivo para acceder a los datos. Para obtener información sobre el esquema usado para el archivo de descarga, vea Esquema de archivo masivo.

Descargar procedimientos recomendados

Siga los procedimientos recomendados para garantizar un uso justo para usted y para todos los clientes de Microsoft Advertising.

Importante

Mientras que los límites de descarga y carga simultáneos exactos están sujetos a cambios, el número de solicitudes pendientes que ha enviado es limitado. Si observa el error 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod, puede volver a enviar la solicitud después de esperar hasta 15 minutos en función de la frecuencia y el tamaño de las solicitudes enviadas. Para obtener más información , consulte Limitación de API masiva.

  • Solicite solo las entidades de descarga masiva que necesite. Los nuevos tipos de registro (filas) y campos (columnas) se pueden agregar en cualquier momento y no debe depender del orden de registros o campos en el archivo de resultados de carga masiva o descarga masiva.

  • Realice una descarga completa solo una vez. A partir de entonces, realice descargas diferenciales. Establezca LastSyncTimeInUTC en la marca de tiempo de la última descarga. El archivo de descarga contiene la marca de tiempo de la descarga en la columna SyncTime del registro Cuenta . No hay ninguna ventaja para realizar una descarga completa cada vez y reduce el rendimiento de todos, incluido el suyo.

  • Sondee las descargas a intervalos razonables. Conoce sus datos mejor que nadie. Si descarga una cuenta que es mucho menos de un millón de palabras clave, considere la posibilidad de sondear a intervalos de 15 a 20 segundos. Si la cuenta contiene aproximadamente un millón de palabras clave, considere la posibilidad de sondear a intervalos de un minuto después de esperar cinco minutos. En el caso de las cuentas con aproximadamente cuatro millones de palabras clave, considere la posibilidad de sondear a intervalos de un minuto después de esperar 10 minutos.

  • Llame a la operación DownloadCampaignsByCampaignIds si la cuenta contiene más de cuatro millones de palabras clave. Se producirá un error al llamar a la operación DownloadCampaignsByAccountIds con una cuenta que contiene más de cuatro millones de palabras clave.

  • Es posible que quiera incluir menos campañas en la solicitud DownloadCampaignsByCampaignIds . Se producirá un error al llamar a la operación DownloadCampaignsByCampaignIds con una cuenta que contiene más de ocho millones de palabras clave. Las solicitudes que especifican menos campañas por llamada normalmente se completan antes que las llamadas que especifican el número máximo permitido.

Carga masiva

Puede enviar el archivo de carga masiva con HTTP POST a una dirección URL proporcionada por el servicio masivo.

Nota:

El límite de tamaño de archivo para la carga en producción es de 100 MB y hasta 4 millones de filas. En espacio aislado , el límite es de 20 000 filas.

Para obtener información sobre el esquema que debe usar para el archivo de carga, consulte Esquema de archivos masivos.

Carga de un archivo masivo

A continuación se muestra información general sobre la configuración de la solicitud y el flujo de trabajo de carga.

Importante

Debe usar las mismas credenciales de usuario en todo el flujo de trabajo GetBulkUploadUrl, HTTP POST y GetBulkUploadStatus .

  1. Establezca el elemento AccountId de la solicitud GetBulkUploadUrl en el identificador de cuenta correspondiente a los datos que se cargarán.

  2. Establezca el elemento ResponseMode de la solicitud GetBulkUploadUrl para especificar si el servicio debe devolver errores y sus datos correspondientes, o solo los errores en el archivo de resultados. Para obtener más información, vea ResponseMode.

  3. Use uploadUrl devuelto con la respuesta GetBulkUploadUrl para enviar el archivo de carga masiva con HTTP POST. El tipo de contenido debe ser multipart/form-data. Los archivos UTF-8 deben incluir la marca de orden de bytes (BOM). La carga comprimida con ZIP debe contener un archivo con formato Csv o Tsv. El archivo ZIP debe estar estructurado correctamente, incluido un final del registro de directorio central.

    Nota:

    No se usa el encabezado de autorización estándar HTTP. Para autenticarse, debe agregar y establecer los elementos de encabezado personalizados de Microsoft Advertising del cliente HTTP, incluidos los encabezados DeveloperToken, CustomerId y CustomerAccountId . También debe establecer las credenciales de usuario a través del elemento de encabezado AuthenticationToken . Para obtener más información, consulte Autenticación con OAuth y Dónde usar las credenciales de API.

    Debe usar las mismas credenciales de usuario en todo el flujo de trabajo GetBulkUploadUrl, HTTP POST y GetBulkUploadStatus .

    Aquí le mostramos un ejemplo.

    POST <UploadUrl> HTTP/1.1
AuthenticationToken: <AuthenticationToken>
DeveloperToken: <DeveloperToken>
CustomerId: <CustomerId>
AccountId: <AccountId>
Content-Type: multipart/form-data;

  4. Compruebe el código de estado de respuesta HTTP. Si el código de estado de respuesta HTTP es 200, Microsoft Advertising recibió correctamente el archivo. Si el código de estado de respuesta HTTP es 401, se produjo un error de autenticación, por ejemplo , AuthenticationToken o DeveloperToken no era válido. Si el código de estado de la respuesta HTTP es 400, también debe comprobar el flujo de respuesta para los códigos de error de operación de la API de Bing Ads , por ejemplo, en el intervalo de 3220 a 3227.

    Este es un mensaje de respuesta de error de ejemplo que indica que la dirección URL ya se había usado para cargar un archivo masivo.

    HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
X-AspNetMvc-Version: 3.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Tue, 12 Jan 2016 17:07:23 GMT
Content-Length: 224

{"TrackingId":"16bd93cc-22fb-4d3c-94be-25adefd06fae","RequestId":"26c3fbf6-3e24-4569-ada3-d4e8b3d0aecc","Code":3224,"ErrorCode":"BulkServiceUrlAlreadyUsedForUpload","Message":"The URL has already been used for file upload."}

  5. La respuesta GetBulkUploadUrl también incluye un RequestId que se pasa a la operación GetBulkUploadStatus . Mientras la carga está pendiente, puede llamar a la operación GetBulkUploadStatus en un bucle hasta que se complete o se produzca un error en la carga. Tiene quince minutos para descargar el archivo de resultados de carga desde el momento en que envía la solicitud de carga. Si no ha descargado correctamente el archivo dentro de este período, se quita del sitio de descarga y es posible que no se recupere. Si pierde esta ventana de oportunidad, podría llamar a una de las operaciones de descarga para obtener los datos de entidad más recientes.

  6. Cuando la operación GetBulkUploadStatus se completa correctamente, devuelve la dirección URL del archivo de resultados de carga. Use la dirección URL para copiar el archivo de resultados localmente. La dirección URL debe usarse en un plazo de quince minutos desde el momento en que la operación GetBulkUploadStatus devuelve la cadena de respuesta De estado completado . Si no inicia la descarga dentro de este período de tiempo, tendrá que llamar a GetBulkUploadStatus de nuevo para obtener una nueva dirección URL.

    Nota:

    El formato del archivo de resultados de carga será Csv o Tsv y coincidirá con el formato del archivo que envió para la carga.

Procedimientos recomendados de carga

Siga los procedimientos recomendados para garantizar un uso justo para usted y para todos los clientes de Microsoft Advertising.

Importante

Mientras que los límites de descarga y carga simultáneos exactos están sujetos a cambios, el número de solicitudes pendientes que ha enviado es limitado. Si observa el error 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod, puede volver a enviar la solicitud después de esperar hasta 15 minutos en función de la frecuencia y el tamaño de las solicitudes enviadas. Para obtener más información , consulte Limitación de API masiva.

  • Los archivos grandes pueden degradar el rendimiento de carga. Es opcional y se recomienda comprimir el archivo para su carga. Si se comprime, debe tener el formato ZIP con la extensión correspondiente. El límite de tamaño de archivo para la carga en producción es de 100 MB y hasta 4 millones de filas. En espacio aislado , el límite es de 20 000 filas. Si puede limitar las cargas simultáneas por cliente por debajo de 5 o 6, considere la posibilidad de dividir el archivo en lugar de acercarse al límite de tamaño del archivo.

  • Limite las cargas simultáneas a 5 o 6 por cliente para cargar archivos en paralelo. Espere en cada subproceso hasta que se procese el archivo anterior y, a continuación, puede volver a usar el subproceso para cargar otro archivo. Por ejemplo, un subproceso puede cargar un archivo y después de que el estado de carga sea Completed, CompletedWithErrors o Failed ese subproceso puede cargar otro archivo.

  • Cargue solo las entidades y campos que va a agregar o actualizar. Si se proporciona, se omitirán los campos de solo lectura, como sugerencias de puja y datos de puntuación de calidad.

  • Cargue un tipo de entidad por archivo para maximizar el rendimiento. Hay algunas excepciones, por ejemplo, al crear nuevas campañas, anuncios y palabras clave, puede ser más eficaz cargarlas junto con claves de referencia. Por ejemplo, si solo actualizas 10 campañas, 500 anuncios y 800 palabras clave, puedes incluirlas en una carga en lugar de dividir las cargas por tipo.

  • Considere si necesita solicitar errores y resultados (ResponseMode = ErrorsAndResults) en el archivo de resultados de carga, o si los errores solo (ResponseMode = ErrorsOnly) serán suficientes. Considere si debe sincronizar o no los resultados con los datos locales. Por ejemplo, si va a actualizar entidades, es posible que solo necesite saber si se produjo algún error y, en ese caso, puede especificar ResponseMode = ErrorsOnly en la solicitud GetBulkUploadUrl . Si va a agregar nuevas entidades, puede especificar ResponseMode = ErrorsAndResults en la solicitud GetBulkUploadUrl para recibir los identificadores de entidad resultantes.

  • En el caso de los reintentos parciales, no cargue todo el archivo si solo un subconjunto de los registros produjo errores. Cargue solo los registros que desea reintentar.

  • No vuelva a intentarlo hasta que el estado de carga sea Completed, CompletedWithErrors o Failed. Si el rendimiento por casualidad no cumple las expectativas, espere el resultado de todos modos.

  • Sondee los resultados de carga a intervalos razonables. Inicialmente, debe esperar un minuto por cada 10 000 filas cargadas. Después del tiempo de espera inicial, considere la posibilidad de sondear en intervalos de un minuto.

Consulta también

Referencia de servicio masivo
Direcciones del servicio web de la API de Bing Ads