Edit

Share via

Image Record - Bulk

  • Article

Defines an image that can be uploaded and downloaded in a bulk file.

You can download all Image records in the account by including the DownloadEntity value of Images in the DownloadCampaignsByAccountIds or DownloadCampaignsByCampaignIds service request. Additionally the download request must include the EntityData scope. For more details about the Bulk service including best practices, see Bulk Download and Upload.

The following Bulk CSV example would add a new image.

Type,Status,Id,Parent Id,Client Id,Modified Time,Text,Url,Name
Format Version,,,,,,,,,,6.0
Image,Active,-20,0,ClientIdGoesHere,,My Image,https://contoso.com/PhotoStock_123.jpg,

If you are using the Bing Ads SDKs for .NET, Java, or Python, you can save time using the BulkServiceManager to upload and download the BulkImage object, instead of calling the service operations directly and writing custom code to parse each field in the bulk file.

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkImage
var bulkImage = new BulkImage
{
    // 'Id' column header in the Bulk file
    Id = imageIdKey,
    // 'Parent Id' column header in the Bulk file
    AccountId = 0,
    // 'Height' column header in the Bulk file
    Height = null,
    // 'Width' column header in the Bulk file
    Width = null,
    // 'Url' column header in the Bulk file
    Url = "https://contoso.com/PhotoStock_123.jpg",
    // 'Sub Type' column header in the Bulk file
    SubType = "GenericImage",
    // 'Text' column header in the Bulk file
    Text = "My Image",
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",
    // 'Status' column header in the Bulk file
    Status = Status.Active
};

uploadEntities.Add(bulkImage);

var entityUploadParameters = new EntityUploadParameters
{
    Entities = uploadEntities,
    ResponseMode = ResponseMode.ErrorsAndResults,
    ResultFileDirectory = FileDirectory,
    ResultFileName = DownloadFileName,
    OverwriteResultFile = true,
};

var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();

For an Image record, the following attribute fields are available in the Bulk File Schema.

Client Id

Used to associate records in the bulk upload file with records in the results file. The value of this field is not used or stored by the server; it is simply copied from the uploaded record to the corresponding result record. It may be any valid string to up 100 in length.

Add: Optional
Delete: Read-only

Height

The height of the image stored in your media library.

The displayed image dimensions will depend in part on your asset link aspect ratios e.g., as defined in the Images field of a Responsive Ad.

Add: Read-only
Delete: Read-only

Id

The system-generated identifier of the image.

Add: Optional. You must either leave this field empty, or specify a negative identifier. A negative identifier set for the image can then be referenced in dependent record types such as the Images field of a Responsive Ad. This is recommended if you are adding new image and new dependent records in the same Bulk file. For more information, see Bulk File Schema Reference Keys.
Delete: Read-only and Required

Modified Time

The date and time that the entity was last updated. The value is in Coordinated Universal Time (UTC).

Note

The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.

Add: Read-only
Delete: Read-only

Parent Id

The system-generated identifier of the account that contains the image.

This bulk field maps to the Id field of the Account record.

Add: Read-only
Delete: Read-only

Status

The status of the image.

Possible values are Active or Deleted.

Add: Optional. The default value is Active.
Delete: Required. The Status must be set to Deleted.

Sub Type

The image sub type indicates the supported aspect ratio of the uploaded image.

We recommend the "GenericImage" with dimensions of 703 width x 368 height or above, in pixels.

All supported sub type values with corresponding dimension and aspect ratio restrictions are described below.

Sub Type Aspect Ratio Minimum Dimension
GenericImage Varies 40 width x 40 height, in pixels
Image16x9 16:9 640 width x 360 height, in pixels
Image15x10 1.5:1 300 width x 200 height, in pixels
Image4x3 4:3 100 width x 75 height, in pixels
Image1x1 1:1 128 width x 128 height, in pixels
Image191x100 1.91:1 703 width x 368 height, in pixels
Image4x1 4:1 512 width x 128 height, in pixels

Note

The maximum width and height in pixels are 2592 and 2048 independently, and you must still maintain one of the supported aspect ratios. For example, if the sub type is Image191x100 and the width is 2592, then the height must be 1357.

Images with animation are not supported. The following MIME types are supported.

  • GIF
  • JPEG
  • PNG

Tip

The PNG images are converted to JPEG. If you are not satisfied with the quality after conversion, we recommend that you provide JPEG directly.

Add: Required
Delete: Read-only

Text

The custom text or label of the image stored in your media library.

Add: Optional
Delete: Read-only

Url

The URL where the image can be accessed.

To upload a new image, you must provide a temporary URL where the Bulk service can access and retrieve your image.

When you download the image, this field contains a URL provided by the Bulk service where you can access and retrieve the stored image as needed.

You can upload a PNG or JPEG image. Images with animation are not supported. The PNG images are converted to JPEG. If you are not satisfied with the quality after conversion, we recommend that you provide JPEG directly.

Add: Required
Delete: Read-only

Width

The width of the image stored in your media library.

The displayed image dimensions will depend in part on your asset link aspect ratios e.g., as defined in the Images field of a Responsive Ad.

Add: Read-only
Delete: Read-only