Microsoft Advertising APIs
Create Ads in Perl

The following Perl example shows how to create advertisements by using the Campaign Management Web service. This example assumes that you have already determined which ad group the ads will be added to; you must substitute your ad group identifier for the $AdGroupId variable that is assigned 50777472 in the following code.

For an example about creating an ad group and retrieving the ad group ID, see Create Ad Groups in Perl.

package adCenterAPI;

# For release code, use the following SOAP::Lite statement.
#use SOAP::Lite ( +maptype => {} );
# For debugging code, use the following SOAP::Lite statement.
use SOAP::Lite ( +trace => all, maptype => {} );

use strict;

eval
{
# Use either the sandbox or production URI.
# This example is for the sandbox URI.
my $URI = "https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/V6";
# The following commented-out line contains the production URI.
#my $URI = "https://adcenterapi.microsoft.com/Api/Advertiser/V6";

# The adCenter API namespace.
my $xmlns = "https://adcenter.microsoft.com/v6";

# The proxy for the Campaign Management Web service.
my $campaignPROXY =
    $URI."/CampaignManagement/CampaignManagementService.svc?wsdl";

# The service operation that will be called.
my $action = 'AddAds';

# The Web service.
my $campaignManagementService = SOAP::Lite->new(
    uri => $URI, 
    proxy => $campaignPROXY, 
    on_action => ( sub { return $action } ));
$campaignManagementService->autotype(0);
$campaignManagementService->multirefinplace(1);
$campaignManagementService->readable(1);

my $username = "username";
my $password = "password";
my $devToken = "devtoken";
my $appToken = "apptoken";
my $customerAccountId = "customeraccountid";
my $customerId = "customerid";
my $AdGroupId = 789; # Application-specific value.

# Assemble the service operation header.
my @header = CreateV6Header(
    $username,
    $password,
    $devToken,
    $appToken,
    $customerAccountId,
    $customerId);

# Create an array of ads.
my @Ads = SOAP::Data->name(Ads => \SOAP::Data->value
(
    SOAP::Data->name(Ad => \SOAP::Data->value
    (
        SOAP::Data->name(DestinationUrl => 
            'http://www.alpineskihouse.com/textad2'),
        SOAP::Data->name(DisplayUrl => 'alpineskihouse.com'),
        SOAP::Data->name(Text => 
            'Alpine Ski House has a great ski selection for you.'),
        SOAP::Data->name(Title => 'Alpine Ski House 1')
    ))->attr({'i:type' => 'TextAd'}),
    SOAP::Data->name(Ad => \SOAP::Data->value
    (
        SOAP::Data->name(DestinationUrl => 
            'http://www.alpineskihouse.com/textad2'),
        SOAP::Data->name(DisplayUrl => 'alpineskihouse.com'),
        SOAP::Data->name(Text => 
            'Alpine Ski House has a great selection of winter clothing for you.'),
        SOAP::Data->name(Title => 'Alpine Ski House 2')
    ))->attr({'i:type' => 'TextAd'}),
))->attr({'xmlns:i' => 'http://www.w3.org/2001/XMLSchema-instance'});

my @params = 
(
    @header,
    SOAP::Data->name("AdGroupId" => $AdGroupId),
    @Ads
);

my $method = SOAP::Data->name
(
    $action.'Request'
)-> attr({xmlns => $xmlns});

my $response = 
    $campaignManagementService->call
    (
        $method => @params
    );

# Check for errors.
if ($response->fault) 
{
    print "$action failed.\n";
    
    # Display the fault code and the fault string.
    print $response->faultcode, " ", $response->faultstring, "\n";

    # Display the adCenter tracking ID.
    my $trackingId = $response->valueof
    (
        '//AdApiFaultDetail/TrackingId'
    );
    print "TrackingId: $trackingId\n";

    # Display any common errors.
    my @commonErrors = $response->valueof
    (
        '//AdApiFaultDetail/Errors/AdApiError'
    );
    foreach my $commonError (@commonErrors)
    {
        print "Operation error ($commonError->{Code}) encountered. ";
        print "$commonError->{Message}\n";
    }
    
    # Display any editorial validation errors.
    my @evErrors = $response->valueof
    (
        '//EditorialApiFaultDetail/EditorialErrors/EditorialError'
    );
    foreach my $evError (@evErrors)
    {
        print "Editorial validation error";
        print " ($evError->{Code}) encountered.\n";
        print "Failed text: $evError->{DisapprovedText}\n";
        print "$evError->{Message}\n";
    }
    
    # Display any operation errors.
    my @operationErrors = $response->valueof
    (
        '//EditorialApiFaultDetail/OperationErrors/OperationError'
    );
    foreach my $operationError (@operationErrors)
    {
        print "Operation error ($operationError->{Code}) encountered. ";
        print "$operationError->{Message}\n";
    }
    
    # Display any batch errors.
    my @batchErrors = $response->valueof
    (
        '//EditorialApiFaultDetail/BatchErrors/BatchError'
    );
    foreach my $batchError (@batchErrors)
    {
        print "Ad group index $batchError->{Index}\n";
        print "Batch error ($batchError->{Code}) encountered. \n";
        print "$batchError->{Message}\n";
        print "$batchError->{Details}\n";
    }
}
else 
{
    print "$action succeeded.\n";

    # Display the adCenter tracking ID.
    my $trackingId = $response->valueof
    (
        '//TrackingId'
    );
    print "TrackingId: $trackingId\n";
    print "\n";

    # Print out the ad IDs.
    my @ids = $response->valueof
    (
        '//AdIds/long'
    );
    print "The following ad IDs were returned by $action:\n";
    foreach my $longval (@ids) 
    {
      print "Ad ID: $longval \n";
    }   
}

sub CreateV6Header
{
    # Method parameters.
    my (
        $username,
        $password,
        $devtoken,
        $apptoken,
        $customeraccountid,
        $customerid) = @_;
    
    # Initialize the application token.
    my $AppToken = SOAP::Header->name
    (
        "ApplicationToken"=>$apptoken
    )->attr({xmlns => $xmlns});
    
    # Initialize the developer token.
    my $DevToken =SOAP::Header->name
    (
        "DeveloperToken"=>$devtoken
    )->attr({xmlns => $xmlns});
    
    # Initialize the user name.
    my $UserName =SOAP::Header->name
    (
        "UserName"=>$username
    )->attr({xmlns => $xmlns});
    
    # Initialize the password.
    my $Password =SOAP::Header->name
    (
        "Password"=>$password
    )->attr({xmlns => $xmlns});
    
    # Initialize the customer account ID.
    my $CustomerAccountId =SOAP::Header->name
    (
        "CustomerAccountId"=>$customeraccountid
    )->attr({xmlns => $xmlns});
    
    # Initialize the customer ID.
    my $CustomerId =SOAP::Header->name
    (
        "CustomerId"=>$customerid
    )->attr({xmlns => $xmlns});
    
    # Assemble the header parameters.
    my @headerParams =
    (
        $AppToken,
        $CustomerAccountId,
        $CustomerId,
        $DevToken,
        $Password,
        $UserName, 
    );
    
    return @headerParams;
}
};
warn $@ if $@;

Each successfully created ad is assigned an ad identifier by adCenter. The ad identifiers are returned in the AdIds element of the AddAdsResponse object.

When you have received the ad identifiers, you should store them locally for future use. For information about why storing the identifiers is recommended, see Creating an Efficient Microsoft adCenter Application. If you don't store the ad identifiers, you can retrieve them by calling the GetAdsByAdGroupId service operation. You can retrieve the elements that are associated with an ad by calling the GetAdsByIds service operation.

Calling GetAdsByAdGroupId or GetAdsByIds consumes some of your API quota. For more information, see Quotas in Microsoft adCenter.

Now that you have successfully created your ads, the next step is to create keywords. For an example about creating keywords, see Create Keywords in Perl.

See Also

Concepts

Hello Microsoft adCenter Sample in Perl
Create Ad Groups in Perl
Create Campaigns in Perl
Create Keywords in Perl

Page view tracker