Create Ad Groups in Perl

Microsoft Advertising APIs

The following Perl example shows how to create ad groups by using the Campaign Management Web service. This example assumes that you have already determined which campaign will be used for the ad groups; you must substitute your campaign identifier for the $CampaignId variable in the following code.

For information about creating a campaign and retrieving the campaign ID, see Create Campaigns 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 the 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 Microsoft 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 common data-type namespace.
my $namespaceArrays = 
    "http://schemas.microsoft.com/2003/10/Serialization/Arrays";

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

# 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 = 1234;
my $customerId = 5678;

my $campaignId = 123456;

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

# Create an array of ad groups.
my @adGroups = SOAP::Data->name(AdGroups => \SOAP::Data->value
(
    SOAP::Data->name(AdGroup => \SOAP::Data->value
    (
        SOAP::Data->name(AdDistribution => 'Search'),
        SOAP::Data->name(BiddingModel => 'Keyword'),
        SOAP::Data->name(LanguageAndRegion => 'EnglishUnitedStates'),
        SOAP::Data->name(Name => 'Eyewear'),
        SOAP::Data->name(EndDate => \SOAP::Data->value
        (
            SOAP::Data->name(Day=>31), 
            SOAP::Data->name(Month=>12), 
            SOAP::Data->name(Year=>2012)
        )),
        SOAP::Data->name(ExactMatchBid => 10.25),
        SOAP::Data->name(NegativeKeywords => \SOAP::Data->value
        (
           SOAP::Data->name('string' => 'dog eyewear'),
           SOAP::Data->name('string' => 'cat eyewear'),
           SOAP::Data->name('string' => 'decorative eyewear')
        ))->attr({'xmlns:i' => $namespaceArrays}),
        SOAP::Data->name(PricingModel => 'Cpc'),
        SOAP::Data->name(StartDate => \SOAP::Data->value
        (
            SOAP::Data->name(Day=>16), 
            SOAP::Data->name(Month=>3), 
            SOAP::Data->name(Year=>2009)
        ))
    )),
    SOAP::Data->name(AdGroup => \SOAP::Data->value
    (
        SOAP::Data->name(AdDistribution => 'Search'),
        SOAP::Data->name(BiddingModel => 'Keyword'),
        SOAP::Data->name(LanguageAndRegion => 'EnglishUnitedStates'),
        SOAP::Data->name(Name => 'Headwear'),
        SOAP::Data->name(EndDate => \SOAP::Data->value
        (
            SOAP::Data->name(Day=>31), 
            SOAP::Data->name(Month=>12), 
            SOAP::Data->name(Year=>2012)
        )),
        SOAP::Data->name(ExactMatchBid => 5),
        SOAP::Data->name(PricingModel => 'Cpc'),
        SOAP::Data->name(StartDate => \SOAP::Data->value
        (
            SOAP::Data->name(Day=>16), 
            SOAP::Data->name(Month=>3), 
            SOAP::Data->name(Year=>2009)
        ))
    ))
))->attr({'xmlns:i' => 'http://www.w3.org/2001/XMLSchema-instance'});;

# Execute the request.
my @params = 
(
    @header,
    @adGroups,
    SOAP::Data->name("CampaignId" => $campaignId)
);

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 adCenter tracking ID.
    my $trackingId = $response->valueof
    (
        '//AdApiFaultDetail/TrackingId'
    );
    print "TrackingId: $trackingId\n";

    # Display any operation errors.
    my @operationErrors = $response->valueof
    (
        '//AdApiFaultDetail/Errors/AdApiError'
    );
    foreach my $operationError (@operationErrors)
    {
        print "Operation error ($operationError->{Code}) encountered. ";
        print "$operationError->{Message}\n";
    }
    
    # Display any batch errors.
    my @batchErrors = $response->valueof
    (
        '//ApiFaultDetail/BatchErrors/BatchError'
    );
    foreach my $batchError (@batchErrors)
    {
        print "Campaign 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 identifier.
    my $trackingId = $response->valueof
    (
        '//TrackingId'
    );
    print "TrackingId: $trackingId\n";
  
    # Display the ad group identifiers.
    my @ids = $response->valueof
    (
        '//AdGroupIds/long'
    );
    
    print "The following ad group identifiers were returned by $action:\n";
    foreach my $longval (@ids) 
    {
        print "Ad Group 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 group is assigned an ad group identifier by Microsoft adCenter. The ad group identifiers are returned in the AdGroupIds element of the AddAdGroupsResponse object.

When you have received the ad group identifiers, you should locally store them for future use. For information about why storing the identifiers is recommended, see Creating an Efficient Microsoft adCenter Application. If you don't store them, you can retrieve them by calling the GetAdGroupsByCampaignId service operation. You can retrieve the elements that are associated with an ad group by calling the GetAdGroupsByIds service operation. Calling GetAdGroupsByCampaignId or GetAdGroupsByIds reduces your API quota. For more information, see Quotas in Microsoft adCenter.

Now that you have successfully created your ad groups, the next step is to create ads and keywords. For examples of these tasks, see Create Ads in Perl and Create Keywords in Perl, respectively.

Concepts

Create Campaigns in Perl
Create Ads in Perl
Create Keywords in Perl
Hello Microsoft adCenter Sample in Perl