Objekte, Methoden und Dienste

Dieser Leitfaden stellt AdWords API-Objekte und -Methoden vor. Dazu werden einige gebräuchliche Verwaltungsaufgaben für Kampagnen als Beispiel herangezogen. Im Anschluss werden die von der API bereitgestellten Dienste beschrieben. Dabei sind auch Links zu den entsprechenden Referenzseiten enthalten.

Die AdWords API ist für fortgeschrittene AdWords-Nutzer bestimmt. Wenn Sie zum ersten Mal mit AdWords arbeiten oder die grundlegenden AdWords-Konzepte noch einmal auffrischen möchten, können Sie sich auf den Seiten zu den AdWords-Grundlagen informieren.

Objekthierarchie und -geltungsbereich

Jedes AdWords-Konto kann als Hierarchie von Objekten betrachtet werden.

Unter jedem Konto gibt es eine oder mehrere Campaigns (Kampagnen), die Ihre aktiven Werbekampagnen darstellen.

Jede Kampagne enthält mehrere AdGroups (Anzeigengruppen), in denen Ihre Anzeigen in logischen Gruppen zusammengefasst sind.

Jede Anzeigengruppe enthält mehrere AdGroupAds- und AdGroupCriteria-Objekte. Ein AdGroupAd-Objekt repräsentiert eine von Ihnen geschaltete Anzeige. Ein AdGroupCriterion-Objekt repräsentiert ein Kriterium – ein Keyword –, mit dem die Schaltung der Anzeigen gesteuert wird.

Sie können Kriterien auf Kampagnenebene angeben, um für die gesamte Kampagne geltende Regeln zur Steuerung der Anzeigenschaltung zu definieren. Außerdem können Sie für die gesamte Kampagne geltende Budgets und Termine angeben.

Schließlich gibt es Anzeigenerweiterungen auf Kampagnenebene, mit denen Sie Ihren Anzeigen zusätzliche Informationen wie Telefonnummer oder Adresse hinzufügen können.

Jedes Objekt in AdWords wird über eine eigene ID identifiziert. Einige dieser IDs sind für alle AdWords-Konten eindeutig (global), andere nur innerhalb eines begrenzten Gültigkeitsbereichs. Die Eindeutigkeit jeder Objekt-ID innerhalb von AdWords ist in der nachfolgenden Tabelle aufgelistet.

Objekt-ID Gültigkeitsbereich der Eindeutigkeit Global eindeutig?
Budget-ID Global Ja
Kampagnen-ID Global Ja
Anzeigengruppen-ID Global Ja
Anzeigen-ID Anzeigengruppe Nein. Das Paar AdGroupId, AdId ist global eindeutig.
ID des Anzeigengruppenkriteriums Anzeigengruppe Nein. Das Paar AdGroupId, CriterionId ist global eindeutig.
ID des Kampagnenkriteriums Kampagne Nein. Das Paar CampaignId, CriterionId ist global eindeutig.
Anzeigenerweiterungen Kampagne Nein. Das Paar CampaignId, AdExtensionId ist global eindeutig.
Feed-ID Global Ja
ID des Feedelements Global Ja
Feed-Attribut-ID Feed Nein
Feed-Mapping-ID Global Ja
Label-ID Global Ja

Diese ID-Regeln sind beim Erstellen einer lokalen Datenbank zur Speicherung Ihrer AdWords-Objekte hilfreich.

Wenn ein Objekt von einem anderen Typ abgeleitet wird, verfügt es auch über das Feld Type. So hat beispielsweise TextAd ein Feld Type, um anzuzeigen, dass es vom Ad-Objekt abgeleitet ist. Wenn Sie eine dynamische Sprache verwenden, können Sie mit diesem Feld den Typ eines Objekts überprüfen, also beispielsweise, ob ein Ad-Objekt vom Typ TextAd ist.

Methoden und Vorgänge

Die AdWords API stellt Dienste zur Verwaltung von AdWords-Objekten bereit. CampaignService dient beispielsweise der Kampagnenverwaltung, AdGroupService der Anzeigengruppenverwaltung usw.

Dienste dieser Art bieten grundsätzlich zwei Standardmethoden: get() und mutate().

Die get()-Methode

Die get()-Methode wird zum Abrufen von AdWords-Objekten verwendet. Mit CampaignService.get() können Sie beispielsweise eine Liste aller Kampagnen abrufen.

Jede get()-Methode übernimmt selector als Eingabe und gibt page zurück. Die AdWords API gibt standardmäßig nicht alle Felder eines Objekts zurück. Sie müssen beim Erstellen des Selektors eine Liste der gewünschten fields angeben.

Verwenden Sie predicates, um die Ergebnisse zu filtern, ordering, um die Reihenfolge der Ergebnisse festzulegen, und dateRange, um den Zeitraum für die abgerufenen Ergebnisse zu begrenzen.

Wenn Sie viele Objekte gleichzeitig abrufen, müssen Sie paging verwenden, da die AdWords API einen SizeLimitError.RESPONSE_SIZE_LIMIT_EXCEEDED-Fehler ausgibt, wenn Sie versuchen viele Objekte ohne Paging abzurufen.

Das folgende Code-Snippet zum Abrufen und Anzeigen aller Kampagnen in einem Konto veranschaulicht diese Konzepte in der Praxis:

Java

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

int offset = 0;

// Create selector.
SelectorBuilder builder = new SelectorBuilder();
Selector selector = builder
    .fields(CampaignField.Id, CampaignField.Name)
    .orderAscBy(CampaignField.Name)
    .offset(offset)
    .limit(PAGE_SIZE)
    .build();

CampaignPage page;
do {
  // Get all campaigns.
  page = campaignService.get(selector);

  // Display campaigns.
  if (page.getEntries() != null) {
    for (Campaign campaign : page.getEntries()) {
      System.out.printf("Campaign with name '%s' and ID %d was found.%n", campaign.getName(),
          campaign.getId());
    }
  } else {
    System.out.println("No campaigns were found.");
  }

  offset += PAGE_SIZE;
  selector = builder.increaseOffsetBy(PAGE_SIZE).build();
} while (offset < page.getTotalNumEntries());

C#

using (CampaignService campaignService =
    (CampaignService) user.GetService(AdWordsService.v201802.CampaignService)) {

  // Create the selector.
  Selector selector = new Selector() {
    fields = new string[] {
      Campaign.Fields.Id, Campaign.Fields.Name, Campaign.Fields.Status
    },
    paging = Paging.Default
  };

  CampaignPage page = new CampaignPage();

  try {
    do {
      // Get the campaigns.
      page = campaignService.get(selector);

      // Display the results.
      if (page != null && page.entries != null) {
        int i = selector.paging.startIndex;
        foreach (Campaign campaign in page.entries) {
          Console.WriteLine("{0}) Campaign with id = '{1}', name = '{2}' and " +
              "status = '{3}' was found.", i + 1, campaign.id,
              campaign.name, campaign.status);
          i++;
        }
      }
      selector.paging.IncreaseOffset();
    } while (selector.paging.startIndex < page.totalNumEntries);
    Console.WriteLine("Number of campaigns found: {0}", page.totalNumEntries);
  } catch (Exception e) {
    throw new System.ApplicationException("Failed to retrieve campaigns", e);
  }

Python

# Initialize appropriate service.
campaign_service = client.GetService('CampaignService', version='v201802')

# Construct selector and get all campaigns.
offset = 0
selector = {
    'fields': ['Id', 'Name', 'Status'],
    'paging': {
        'startIndex': str(offset),
        'numberResults': str(PAGE_SIZE)
    }
}

more_pages = True
while more_pages:
  page = campaign_service.get(selector)

  # Display results.
  if 'entries' in page:
    for campaign in page['entries']:
      print ('Campaign with id "%s", name "%s", and status "%s" was '
             'found.' % (campaign['id'], campaign['name'],
                         campaign['status']))
  else:
    print 'No campaigns were found.'
  offset += PAGE_SIZE
  selector['paging']['startIndex'] = str(offset)
  more_pages = offset < int(page['totalNumEntries'])

PHP

$campaignService = $adWordsServices->get($session, CampaignService::class);

// Create selector.
$selector = new Selector();
$selector->setFields(['Id', 'Name']);
$selector->setOrdering([new OrderBy('Name', SortOrder::ASCENDING)]);
$selector->setPaging(new Paging(0, self::PAGE_LIMIT));

$totalNumEntries = 0;
do {
    // Make the get request.
    $page = $campaignService->get($selector);

    // Display results.
    if ($page->getEntries() !== null) {
        $totalNumEntries = $page->getTotalNumEntries();
        foreach ($page->getEntries() as $campaign) {
            printf(
                "Campaign with ID %d and name '%s' was found.\n",
                $campaign->getId(),
                $campaign->getName()
            );
        }
    }

    // Advance the paging index.
    $selector->getPaging()->setStartIndex(
        $selector->getPaging()->getStartIndex() + self::PAGE_LIMIT
    );
} while ($selector->getPaging()->getStartIndex() < $totalNumEntries);

printf("Number of results found: %d\n", $totalNumEntries);

Perl

# Create selector.
my $paging = Google::Ads::AdWords::v201802::Paging->new({
    startIndex    => 0,
    numberResults => PAGE_SIZE
});
my $selector = Google::Ads::AdWords::v201802::Selector->new({
    fields   => ["Id", "Name"],
    ordering => [
      Google::Ads::AdWords::v201802::OrderBy->new({
          field     => "Name",
          sortOrder => "ASCENDING"
        })
    ],
    paging => $paging
  });

# Paginate through results.
# The contents of the subroutine will be executed for each campaign.
Google::Ads::AdWords::Utilities::PageProcessor->new({
    client   => $client,
    service  => $client->CampaignService(),
    selector => $selector
  }
  )->process_entries(
  sub {
    my ($campaign) = @_;
    printf "Campaign with name \"%s\" and id \"%d\" was found.\n",
      $campaign->get_name(), $campaign->get_id();
  });

Ruby

campaign_srv = adwords.service(:CampaignService, API_VERSION)

# Get all the campaigns for this account.
selector = {
  :fields => ['Id', 'Name', 'Status'],
  :ordering => [
    {:field => 'Name', :sort_order => 'ASCENDING'}
  ],
  :paging => {
    :start_index => 0,
    :number_results => PAGE_SIZE
  }
}

# Set initial values.
offset, page = 0, {}

begin
  page = campaign_srv.get(selector)
  if page[:entries]
    page[:entries].each do |campaign|
      puts "Campaign ID %d, name '%s' and status '%s'" %
          [campaign[:id], campaign[:name], campaign[:status]]
    end
    # Increment values to request the next page.
    offset += PAGE_SIZE
    selector[:paging][:start_index] = offset
  end
end while page[:total_num_entries] > offset

if page.include?(:total_num_entries)
  puts "\tTotal number of campaigns found: %d." % [page[:total_num_entries]]
end

VB.NET

Using campaignService As CampaignService = CType(user.GetService(
    AdWordsService.v201802.CampaignService), CampaignService)

  ' Create the selector.
  Dim selector As New Selector
  selector.fields = New String() {
    Campaign.Fields.Id, Campaign.Fields.Name, Campaign.Fields.Status
  }
  selector.paging = Paging.Default

  Dim page As New CampaignPage

  Try
    Do
      ' Get the campaigns.
      page = campaignService.get(selector)

      ' Display the results.
      If ((Not page Is Nothing) AndAlso (Not page.entries Is Nothing)) Then
        Dim i As Integer = selector.paging.startIndex
        For Each campaign As Campaign In page.entries
          Console.WriteLine("{0}) Campaign with id = '{1}', name = '{2}' and status = " &
            "'{3}' was found.", i + 1, campaign.id, campaign.name, campaign.status)
          i += 1
        Next
      End If
      selector.paging.IncreaseOffset()
    Loop While (selector.paging.startIndex < page.totalNumEntries)
    Console.WriteLine("Number of campaigns found: {0}", page.totalNumEntries)
  Catch e As Exception
    Throw New System.ApplicationException("Failed to retrieve campaign(s).", e)
  End Try

Auf der Referenzseite mit Selektorfeldern finden Sie die verfügbaren Selektorfelder für die verschiedenen Dienste.

Unsere Clientbibliotheken enthalten Codebeispiele, die die get()-Methode für alle Dienste zur Kampagnenverwaltung verwenden. Im Folgenden finden Sie Beispiele aus der Clientbibliothek für Dienste zur Kampagnenverwaltung für die einzelnen Programmiersprachen.

Die query()-Methode

Die query()-Methode stellt eine Alternative zur get()-Methode dar. Anders als diese verwendet "query()" allerdings keine Selektoren, sondern die SQL-ähnliche Sprache AWQL (AdWords Query Language). Die Codierung der gleichen Anforderung in AWQL ist in der Regel effizienter. Die query()-Methode wird von den meisten gängigen Diensten unterstützt. AWQL unterstützt nicht das Ändern von Daten.

Das Beispiel von oben veranschaulicht die Effizienz von AWQL. Statt vier Codezeilen für den Selektor zu schreiben, können Sie einen einzelnen String erstellen, der dieselben Informationen enthält.

Java

String query = "SELECT Id, Name, Status ORDER BY Name";

C#

// Create the query.
string query = "SELECT Id, Name, Status ORDER BY Name";

Python

query = (adwords.ServiceQueryBuilder()
         .Select('Id', 'Name', 'Status')
         .Where('Status').EqualTo('ENABLED')
         .OrderBy('Name')
         .Limit(0, PAGE_SIZE)
         .Build())

PHP

$query = (new ServiceQueryBuilder())
    ->select(['Id', 'Name', 'Status'])
    ->orderByAsc('Name')
    ->limit(0, self::PAGE_LIMIT)
    ->build();

Perl

my $query =
  Google::Ads::AdWords::Utilities::ServiceQueryBuilder->new(
  {client => $client})
  ->select(["Id", "Name", "Status"])
  ->order_by("Name")
  ->build();

Ruby

# Get all the campaigns for this account.
query_builder = adwords.service_query_builder do |b|
  b.select('Id', 'Name', 'Status')
  b.order_by_asc('Name')
  b.limit(0, PAGE_SIZE)
end
query = query_builder.build

VB.NET

' Create the query.
Dim query As String = "SELECT Id, Name, Status ORDER BY Name"

Dieser String enthält keine FROM-Klausel. Das liegt daran, dass die query()-Methode des verwendeten Diensts die Auswahl bereits vorgibt. AWQL unterstützt die FROM-Klausel nur für Berichte. Rufen Sie einfach die query()-Methode des Diensts auf, um diesen String zu verwenden.

Java

CampaignPage page = null;
do {
  String pageQuery = query + String.format(" LIMIT %d, %d", offset, PAGE_SIZE);
  // Get all campaigns.
  page = campaignService.query(pageQuery);

  // Display campaigns.
  if (page.getEntries() != null) {
    for (Campaign campaign : page.getEntries()) {
      System.out.printf("Campaign with name '%s' and ID %d was found.%n", campaign.getName(),
          campaign.getId());
    }
  } else {
    System.out.println("No campaigns were found.");
  }

  offset += PAGE_SIZE;
} while (offset < page.getTotalNumEntries());

C#

int offset = 0;
int pageSize = 500;

CampaignPage page = new CampaignPage();

try {
  do {
    string queryWithPaging = string.Format("{0} LIMIT {1}, {2}", query, offset, pageSize);

    // Get the campaigns.
    page = campaignService.query(queryWithPaging);

    // Display the results.
    if (page != null && page.entries != null) {
      int i = offset;
      foreach (Campaign campaign in page.entries) {
        Console.WriteLine("{0}) Campaign with id = '{1}', name = '{2}' and status = " +
            "'{3}' was found.", i + 1, campaign.id, campaign.name, campaign.status);
        i++;
      }
    }
    offset += pageSize;
  } while (offset < page.totalNumEntries);
  Console.WriteLine("Number of campaigns found: {0}", page.totalNumEntries);
} catch (Exception e) {
  throw new System.ApplicationException("Failed to retrieve campaigns", e);
}

Python

for page in query.Pager(campaign_service):
  # Display results.
  if 'entries' in page:
    for campaign in page['entries']:
      print ('Campaign with id "%s", name "%s", and status "%s" was '
             'found.' % (campaign['id'], campaign['name'],
                         campaign['status']))
  else:
    print 'No campaigns were found.'

PHP

do {

    // Advance the paging offset in subsequent iterations only.
    if (isset($page)) {
        $query->nextPage();
    }

    // Make a request using an AWQL string. This request will return the
    // first page containing up to `self::PAGE_LIMIT` results
    $page = $campaignService->query(sprintf('%s', $query));

    // Display results from second and subsequent pages.
    if ($page->getEntries() !== null) {
        foreach ($page->getEntries() as $campaign) {
            printf(
                "Campaign with ID %d and name '%s' was found.\n",
                $campaign->getId(),
                $campaign->getName()
            );
        }
    }
} while ($query->hasNext($page));

printf("Number of results found: %d\n",
    $page->getTotalNumEntries());

Perl

Google::Ads::AdWords::Utilities::PageProcessor->new({
    client    => $client,
    service   => $client->CampaignService(),
    query     => $query,
    page_size => PAGE_SIZE
  }
  )->process_entries(
  sub {
    my ($campaign) = @_;
    printf "Campaign with name \"%s\" and id \"%d\" was found.\n",
      $campaign->get_name(), $campaign->get_id();
  });

Ruby

loop do
  page_query = query.to_s
  page = campaign_srv.query(page_query)
  if page[:entries]
    page[:entries].each do |campaign|
      puts "Campaign ID %d, name '%s' and status '%s'" %
          [campaign[:id], campaign[:name], campaign[:status]]
    end
  end
  break unless query.has_next(page)
  query.next_page
end

if page.include?(:total_num_entries)
  puts "\tTotal number of campaigns found: %d." % page[:total_num_entries]
end

VB.NET

Dim offset As Long = 0
Dim pageSize As Long = 500

Dim page As New CampaignPage()

Try
  Do
    Dim queryWithPaging As String = String.Format("{0} LIMIT {1}, {2}", query, offset,
        pageSize)

    ' Get the campaigns.
    page = campaignService.query(queryWithPaging)

    ' Display the results.
    If ((Not page Is Nothing) AndAlso (Not page.entries Is Nothing)) Then
      Dim i As Integer = CInt(offset)
      For Each campaign As Campaign In page.entries
        Console.WriteLine("{0}) Campaign with id = '{1}', name = '{2}' and status = " &
            "'{3}' was found.", i, campaign.id, campaign.name, campaign.status)
        i += 1
      Next
    End If
    offset = offset + pageSize
  Loop While (offset < page.totalNumEntries)
  Console.WriteLine("Number of campaigns found: {0}", page.totalNumEntries)
Catch e As Exception
  Throw New System.ApplicationException("Failed to retrieve campaign(s).", e)
End Try

Der obige Code führt zu demselben Ergebnis wie die get()-Methode. Mit AWQL kann das Schreiben einer Anfrage einfacher und kürzer als mit einem get()-Aufruf sein. Weitere Informationen finden Sie im AWQL-Handbuch.

Die mutate()-Methode

Die mutate()-Methode wird verwendet, um ein AdWords-Objekt zu ändern (erstellen, aktualisieren oder entfernen).

Zum Ändern eines Objekts müssen Sie ein entsprechendes Operation-Objekt erstellen. So müssen Sie beispielsweise eine CampaignOperation erstellen, um eine Campaign zu ändern.

Das Feld operator definiert den Typ des durchzuführenden Vorgangs (ADD, SET oder REMOVE). Das Operandenfeld enthält das zu ändernde Objekt. Mit dem folgenden Code-Snippet werden Kampagnen hinzugefügt:

Java

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Create campaign.
Campaign campaign = new Campaign();
campaign.setName("Interplanetary Cruise #" + System.currentTimeMillis());

// Recommendation: Set the campaign to PAUSED when creating it to prevent
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
campaign.setStatus(CampaignStatus.PAUSED);

BiddingStrategyConfiguration biddingStrategyConfiguration = new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);

// You can optionally provide a bidding scheme in place of the type.
ManualCpcBiddingScheme cpcBiddingScheme = new ManualCpcBiddingScheme();
biddingStrategyConfiguration.setBiddingScheme(cpcBiddingScheme);

campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// You can optionally provide these field(s).
campaign.setStartDate(new DateTime().plusDays(1).toString("yyyyMMdd"));
campaign.setEndDate(new DateTime().plusDays(30).toString("yyyyMMdd"));
campaign.setFrequencyCap(new FrequencyCap(5L, TimeUnit.DAY, Level.ADGROUP));

// Only the budgetId should be sent, all other fields will be ignored by CampaignService.
Budget budget = new Budget();
budget.setBudgetId(budgetId);
campaign.setBudget(budget);

campaign.setAdvertisingChannelType(AdvertisingChannelType.SEARCH);

// Set the campaign network options to Search and Search Network.
NetworkSetting networkSetting = new NetworkSetting();
networkSetting.setTargetGoogleSearch(true);
networkSetting.setTargetSearchNetwork(true);
networkSetting.setTargetContentNetwork(false);
networkSetting.setTargetPartnerSearchNetwork(false);
campaign.setNetworkSetting(networkSetting);

// Set options that are not required.
GeoTargetTypeSetting geoTarget = new GeoTargetTypeSetting();
geoTarget.setPositiveGeoTargetType(GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE);
campaign.setSettings(new Setting[] {geoTarget});

// You can create multiple campaigns in a single request.
Campaign campaign2 = new Campaign();
campaign2.setName("Interplanetary Cruise banner #" + System.currentTimeMillis());
campaign2.setStatus(CampaignStatus.PAUSED);
BiddingStrategyConfiguration biddingStrategyConfiguration2 = new BiddingStrategyConfiguration();
biddingStrategyConfiguration2.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);
campaign2.setBiddingStrategyConfiguration(biddingStrategyConfiguration2);

Budget budget2 = new Budget();
budget2.setBudgetId(budgetId);
campaign2.setBudget(budget2);

campaign2.setAdvertisingChannelType(AdvertisingChannelType.DISPLAY);

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.ADD);
CampaignOperation operation2 = new CampaignOperation();
operation2.setOperand(campaign2);
operation2.setOperator(Operator.ADD);

CampaignOperation[] operations = new CampaignOperation[] {operation, operation2};

// Add campaigns.
CampaignReturnValue result = campaignService.mutate(operations);

// Display campaigns.
for (Campaign campaignResult : result.getValue()) {
  System.out.printf("Campaign with name '%s' and ID %d was added.%n", campaignResult.getName(),
      campaignResult.getId());
}

C#

List<CampaignOperation> operations = new List<CampaignOperation>();

for (int i = 0; i < NUM_ITEMS; i++) {
  // Create the campaign.
  Campaign campaign = new Campaign();
  campaign.name = "Interplanetary Cruise #" + ExampleUtilities.GetRandomString();
  campaign.advertisingChannelType = AdvertisingChannelType.SEARCH;

  // Recommendation: Set the campaign to PAUSED when creating it to prevent
  // the ads from immediately serving. Set to ENABLED once you've added
  // targeting and the ads are ready to serve.
  campaign.status = CampaignStatus.PAUSED;

  BiddingStrategyConfiguration biddingConfig = new BiddingStrategyConfiguration();
  biddingConfig.biddingStrategyType = BiddingStrategyType.MANUAL_CPC;
  campaign.biddingStrategyConfiguration = biddingConfig;

  campaign.budget = new Budget();
  campaign.budget.budgetId = budget.budgetId;

  // Set the campaign network options.
  campaign.networkSetting = new NetworkSetting();
  campaign.networkSetting.targetGoogleSearch = true;
  campaign.networkSetting.targetSearchNetwork = true;
  campaign.networkSetting.targetContentNetwork = false;
  campaign.networkSetting.targetPartnerSearchNetwork = false;

  // Set the campaign settings for Advanced location options.
  GeoTargetTypeSetting geoSetting = new GeoTargetTypeSetting();
  geoSetting.positiveGeoTargetType = GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE;
  geoSetting.negativeGeoTargetType = GeoTargetTypeSettingNegativeGeoTargetType.DONT_CARE;

  campaign.settings = new Setting[] { geoSetting };

  // Optional: Set the start date.
  campaign.startDate = DateTime.Now.AddDays(1).ToString("yyyyMMdd");

  // Optional: Set the end date.
  campaign.endDate = DateTime.Now.AddYears(1).ToString("yyyyMMdd");

  // Optional: Set the frequency cap.
  FrequencyCap frequencyCap = new FrequencyCap();
  frequencyCap.impressions = 5;
  frequencyCap.level = Level.ADGROUP;
  frequencyCap.timeUnit = TimeUnit.DAY;
  campaign.frequencyCap = frequencyCap;

  // Create the operation.
  CampaignOperation operation = new CampaignOperation();
  operation.@operator = Operator.ADD;
  operation.operand = campaign;

  operations.Add(operation);
}

try {
  // Add the campaign.
  CampaignReturnValue retVal = campaignService.mutate(operations.ToArray());

  // Display the results.
  if (retVal != null && retVal.value != null && retVal.value.Length > 0) {
    foreach (Campaign newCampaign in retVal.value) {
      Console.WriteLine("Campaign with name = '{0}' and id = '{1}' was added.",
          newCampaign.name, newCampaign.id);
    }
  } else {
    Console.WriteLine("No campaigns were added.");
  }
} catch (Exception e) {
  throw new System.ApplicationException("Failed to add campaigns.", e);
}

Python

operations = [{
    'operator': 'ADD',
    'operand': {
        'name': 'Interplanetary Cruise #%s' % uuid.uuid4(),
        # Recommendation: Set the campaign to PAUSED when creating it to
        # stop the ads from immediately serving. Set to ENABLED once you've
        # added targeting and the ads are ready to serve.
        'status': 'PAUSED',
        'advertisingChannelType': 'SEARCH',
        'biddingStrategyConfiguration': {
            'biddingStrategyType': 'MANUAL_CPC',
        },
        'endDate': (datetime.datetime.now() +
                    datetime.timedelta(365)).strftime('%Y%m%d'),
        # Note that only the budgetId is required
        'budget': {
            'budgetId': budget_id
        },
        'networkSetting': {
            'targetGoogleSearch': 'true',
            'targetSearchNetwork': 'true',
            'targetContentNetwork': 'false',
            'targetPartnerSearchNetwork': 'false'
        },
        # Optional fields
        'startDate': (datetime.datetime.now() +
                      datetime.timedelta(1)).strftime('%Y%m%d'),
        'frequencyCap': {
            'impressions': '5',
            'timeUnit': 'DAY',
            'level': 'ADGROUP'
        },
        'settings': [
            {
                'xsi_type': 'GeoTargetTypeSetting',
                'positiveGeoTargetType': 'DONT_CARE',
                'negativeGeoTargetType': 'DONT_CARE'
            }
        ]
    }
}, {
    'operator': 'ADD',
    'operand': {
        'name': 'Interplanetary Cruise banner #%s' % uuid.uuid4(),
        'status': 'PAUSED',
        'biddingStrategyConfiguration': {
            'biddingStrategyType': 'MANUAL_CPC'
        },
        'endDate': (datetime.datetime.now() +
                    datetime.timedelta(365)).strftime('%Y%m%d'),
        # Note that only the budgetId is required
        'budget': {
            'budgetId': budget_id
        },
        'advertisingChannelType': 'DISPLAY'
    }
}]
campaigns = campaign_service.mutate(operations)

# Display results.
for campaign in campaigns['value']:
  print ('Campaign with name "%s" and id "%s" was added.'
         % (campaign['name'], campaign['id']))

PHP

$campaignService = $adWordsServices->get($session, CampaignService::class);

$operations = [];

// Create a campaign with required and optional settings.
$campaign = new Campaign();
$campaign->setName('Interplanetary Cruise #' . uniqid());
$campaign->setAdvertisingChannelType(AdvertisingChannelType::SEARCH);

// Set shared budget (required).
$campaign->setBudget(new Budget());
$campaign->getBudget()->setBudgetId($budget->getBudgetId());

// Set bidding strategy (required).
$biddingStrategyConfiguration = new BiddingStrategyConfiguration();
$biddingStrategyConfiguration->setBiddingStrategyType(
    BiddingStrategyType::MANUAL_CPC
);

// You can optionally provide a bidding scheme in place of the type.
$biddingScheme = new ManualCpcBiddingScheme();
$biddingStrategyConfiguration->setBiddingScheme($biddingScheme);

$campaign->setBiddingStrategyConfiguration($biddingStrategyConfiguration);

// Set network targeting (optional).
$networkSetting = new NetworkSetting();
$networkSetting->setTargetGoogleSearch(true);
$networkSetting->setTargetSearchNetwork(true);
$networkSetting->setTargetContentNetwork(true);
$campaign->setNetworkSetting($networkSetting);

// Set additional settings (optional).
// Recommendation: Set the campaign to PAUSED when creating it to stop
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
$campaign->setStatus(CampaignStatus::PAUSED);
$campaign->setStartDate(date('Ymd', strtotime('+1 day')));
$campaign->setEndDate(date('Ymd', strtotime('+1 month')));

// Set frequency cap (optional).
$frequencyCap = new FrequencyCap();
$frequencyCap->setImpressions(5);
$frequencyCap->setTimeUnit(TimeUnit::DAY);
$frequencyCap->setLevel(Level::ADGROUP);
$campaign->setFrequencyCap($frequencyCap);

// Set advanced location targeting settings (optional).
$geoTargetTypeSetting = new GeoTargetTypeSetting();
$geoTargetTypeSetting->setPositiveGeoTargetType(
    GeoTargetTypeSettingPositiveGeoTargetType::DONT_CARE
);
$geoTargetTypeSetting->setNegativeGeoTargetType(
    GeoTargetTypeSettingNegativeGeoTargetType::DONT_CARE
);
$campaign->setSettings([$geoTargetTypeSetting]);

// Create a campaign operation and add it to the operations list.
$operation = new CampaignOperation();
$operation->setOperand($campaign);
$operation->setOperator(Operator::ADD);
$operations[] = $operation;

// Create a campaign with only required settings.
$campaign = new Campaign();
$campaign->setName('Interplanetary Cruise #' . uniqid());
$campaign->setAdvertisingChannelType(AdvertisingChannelType::DISPLAY);

// Set shared budget (required).
$campaign->setBudget(new Budget());
$campaign->getBudget()->setBudgetId($budget->getBudgetId());

// Set bidding strategy (required).
$biddingStrategyConfiguration = new BiddingStrategyConfiguration();
$biddingStrategyConfiguration->setBiddingStrategyType(
    BiddingStrategyType::MANUAL_CPC
);
$campaign->setBiddingStrategyConfiguration($biddingStrategyConfiguration);

$campaign->setStatus(CampaignStatus::PAUSED);

// Create a campaign operation and add it to the operations list.
$operation = new CampaignOperation();
$operation->setOperand($campaign);
$operation->setOperator(Operator::ADD);
$operations[] = $operation;

// Create the campaigns on the server and print out some information for
// each created campaign.
$result = $campaignService->mutate($operations);
foreach ($result->getValue() as $campaign) {
    printf(
        "Campaign with name '%s' and ID %d was added.\n",
        $campaign->getName(),
        $campaign->getId()
    );
}

Perl

# Create campaigns.
my $num_campaigns = 2;
my @operations    = ();
for (my $i = 0 ; $i < $num_campaigns ; $i++) {
  my (undef, undef, undef, $mday, $mon, $year) = localtime(time);
  my $today = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
  (undef, undef, undef, $mday, $mon, $year) = localtime(time + 60 * 60 * 24);
  my $tomorrow = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
  my $campaign = Google::Ads::AdWords::v201802::Campaign->new({
      name => "Interplanetary Cruise #" . uniqid(),
      # Bidding strategy (required).
      biddingStrategyConfiguration =>
        Google::Ads::AdWords::v201802::BiddingStrategyConfiguration->new({
          biddingStrategyType => "MANUAL_CPC",
          # You can optionally provide a bidding scheme in place of the type.
        }
        ),
      # Budget (required) - note only the budgetId is required.
      budget =>
        Google::Ads::AdWords::v201802::Budget->new({budgetId => $budgetId}),
      # Create a Search Network with Display Select campaign.
      # To create a Display Only campaign, omit networkSetting and use the
      # DISPLAY advertisingChannelType.
      # NetworkSetting (optional).
      networkSetting => Google::Ads::AdWords::v201802::NetworkSetting->new({
          targetGoogleSearch         => 1,
          targetSearchNetwork        => 1,
          targetContentNetwork       => 1,
          targetPartnerSearchNetwork => 0
        }
      ),
      # Advertising channel type (required).
      advertisingChannelType => "SEARCH",
      # Frequency cap (non-required).
      frequencyCap => Google::Ads::AdWords::v201802::FrequencyCap->new({
          impressions => 5,
          timeUnit    => "DAY",
          level       => "ADGROUP"
        }
      ),
      settings => [
        # Advanced location targeting settings (non-required).
        Google::Ads::AdWords::v201802::GeoTargetTypeSetting->new({
            positiveGeoTargetType => "DONT_CARE",
            negativeGeoTargetType => "DONT_CARE"
          }
        ),
      ],
      # Additional properties (non-required).
      startDate                   => $today,
      endDate                     => $tomorrow,
      # Recommendation: Set the campaign to PAUSED when creating it to stop
      # the ads from immediately serving. Set to ENABLED once you've added
      # targeting and the ads are ready to serve.
      status                      => "PAUSED"
    });

  # Create operation.
  my $campaign_operation =
    Google::Ads::AdWords::v201802::CampaignOperation->new({
      operator => "ADD",
      operand  => $campaign
    });
  push @operations, $campaign_operation;
}

# Add campaigns.
my $result = $client->CampaignService()->mutate({operations => \@operations});

# Display campaigns.
foreach my $campaign (@{$result->get_value()}) {
  printf "Campaign with name \"%s\" and id \"%s\" was added.\n",
    $campaign->get_name(), $campaign->get_id();
}

Ruby

campaign_srv = adwords.service(:CampaignService, API_VERSION)

# Create campaigns.
campaigns = [
  {
    :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
    # Recommendation: Set the campaign to PAUSED when creating it to stop the
    # ads from immediately serving. Set to ENABLED once you've added
    # targeting and the ads are ready to serve.
    :status => 'PAUSED',
    :bidding_strategy_configuration => {
      :bidding_strategy_type => 'MANUAL_CPC'
    },
    # Budget (required) - note only the budget ID is required.
    :budget => {:budget_id => budget_id},
    :advertising_channel_type => 'SEARCH',
    # Optional fields:
    :start_date =>
        DateTime.parse((Date.today + 1).to_s).strftime('%Y%m%d'),
    :network_setting => {
      :target_google_search => true,
      :target_search_network => true,
      :target_content_network => true
    },
    :settings => [
      {
        :xsi_type => 'GeoTargetTypeSetting',
        :positive_geo_target_type => 'DONT_CARE',
        :negative_geo_target_type => 'DONT_CARE'
      }
    ],
    :frequency_cap => {
      :impressions => '5',
      :time_unit => 'DAY',
      :level => 'ADGROUP'
    }
  },
  {
    :name => "Interplanetary Cruise banner #%d" % (Time.new.to_f * 1000).to_i,
    :status => 'PAUSED',
    :bidding_strategy_configuration => {
      :bidding_strategy_type => 'MANUAL_CPC'
    },
    :budget => {:budget_id => budget_id},
    :advertising_channel_type => 'DISPLAY'
  }
]

# Prepare for adding campaign.
operations = campaigns.map do |campaign|
  {:operator => 'ADD', :operand => campaign}
end

# Add campaign.
response = campaign_srv.mutate(operations)
if response and response[:value]
  response[:value].each do |campaign|
    puts "Campaign with name '%s' and ID %d was added." %
        [campaign[:name], campaign[:id]]
  end
else
  raise new StandardError, 'No campaigns were added.'
end

VB.NET

  Dim operations As New List(Of CampaignOperation)

  For i As Integer = 1 To NUM_ITEMS
    ' Create the campaign.
    Dim campaign As New Campaign
    campaign.name = "Interplanetary Cruise #" & ExampleUtilities.GetRandomString
    campaign.advertisingChannelType = AdvertisingChannelType.SEARCH

    ' Recommendation: Set the campaign to PAUSED when creating it to prevent
    ' the ads from immediately serving. Set to ENABLED once you've added
    ' targeting and the ads are ready to serve.
    campaign.status = CampaignStatus.PAUSED

    Dim biddingConfig As New BiddingStrategyConfiguration()
    biddingConfig.biddingStrategyType = BiddingStrategyType.MANUAL_CPC
    campaign.biddingStrategyConfiguration = biddingConfig

    ' Set the campaign budget.
    campaign.budget = New Budget
    campaign.budget.budgetId = budget.budgetId

    ' Set the campaign network options.
    campaign.networkSetting = New NetworkSetting
    campaign.networkSetting.targetGoogleSearch = True
    campaign.networkSetting.targetSearchNetwork = True
    campaign.networkSetting.targetContentNetwork = False
    campaign.networkSetting.targetPartnerSearchNetwork = False

    ' Set the campaign geo target and keyword match settings.
    Dim geoSetting As New GeoTargetTypeSetting
    geoSetting.positiveGeoTargetType = GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE
    geoSetting.negativeGeoTargetType = GeoTargetTypeSettingNegativeGeoTargetType.DONT_CARE

    campaign.settings = New Setting() {geoSetting}

    ' Optional: Set the start date.
    campaign.startDate = DateTime.Now.AddDays(1).ToString("yyyyMMdd")

    ' Optional: Set the end date.
    campaign.endDate = DateTime.Now.AddYears(1).ToString("yyyyMMdd")

    ' Optional: Set the frequency cap.
    Dim frequencyCap As New FrequencyCap
    frequencyCap.impressions = 5
    frequencyCap.level = Level.ADGROUP
    frequencyCap.timeUnit = TimeUnit.DAY
    campaign.frequencyCap = frequencyCap

    ' Create the operation.
    Dim operation As New CampaignOperation
    operation.operator = [Operator].ADD
    operation.operand = campaign
    operations.Add(operation)
  Next

  Try
    ' Add the campaign.
    Dim retVal As CampaignReturnValue = campaignService.mutate(operations.ToArray())

    ' Display the results.
    If ((Not retVal Is Nothing) AndAlso (Not retVal.value Is Nothing) AndAlso
      (retVal.value.Length > 0)) Then
      For Each newCampaign As Campaign In retVal.value
        Console.WriteLine("Campaign with name = '{0}' and id = '{1}' was added.",
            newCampaign.name, newCampaign.id)
      Next
    Else
      Console.WriteLine("No campaigns were added.")
    End If
  Catch e As Exception
    Throw New System.ApplicationException("Failed to add campaigns.", e)
  End Try
End Using

Unsere Clientbibliotheken enthalten Codebeispiele für die mutate()-Methode für alle Dienste zur Kampagnenverwaltung.

Wenn Objekte geändert werden, ist die Anzahl der Objekte eines bestimmten Typs, die in einem AdWords-Konto enthalten sein können, begrenzt. Weitere Informationen zu den Begrenzungen der einzelnen Typen von AdWords-Objekten erhalten Sie in diesem Hilfeartikel. Verwenden Sie diese Begrenzungen nur als Richtwerte für die Planung Ihrer Kampagnen und programmieren Sie diese Begrenzungen nicht in Ihre Anwendung.

Bei mutate()-Aufrufen sollten nach Möglichkeit mehrere Operationen pro Anfrage gesendet werden, statt mehrerer Anfragen mit je einer Operation. Dies reduziert die Anzahl der Anfragen beim Server und steigert somit die Leistung Ihrer Anwendung.

Ordnen Sie außerdem Anfragen nach Vorgängen einem übergeordneten Element zu. Wenn Sie beispielsweise Anzeigen hinzufügen, versuchen Sie, Ihre Anfragen so zu gruppieren, dass Anzeigen immer nur einer Anzeigengruppe gleichzeitig hinzugefügt werden, statt Anzeigen mit einer einzelnen Anfrage direkt mehreren Anzeigengruppen hinzuzufügen. Weitere Informationen finden Sie im Best Practices-Leitfaden.

Das operator-Feld

Wie bereits oben erwähnt, definiert das operator-Feld die Art des gewünschten mutate()-Vorgangs: ADD, SET oder REMOVE.

Mit ADD erstellen Sie ein neues Objekt, mit SET aktualisieren Sie ein vorhandenes Objekt und mit REMOVE entfernen Sie ein vorhandenes Objekt. Einige Operatoren sind jedoch möglicherweise nicht für alle Dienste anwendbar.

So kann beispielsweise eine AdWords-Kampagne nach dem Erstellen nicht dauerhaft gelöscht, sondern nur als REMOVED gekennzeichnet werden. Sie ist dann zwar REMOVED, doch können Sie ihre Details und Statistiken weiterhin abfragen.

Die AdWords API unterstützt daher den Operator REMOVE für "CampaignService" nicht. Sie müssen den Status einer Kampagne mit dem REMOVED-Operator in SET ändern.

Kampagnenziele lassen sich hingegen nicht ändern. Für diese Objekte können Sie nur ADD oder REMOVE verwenden.

In der folgenden Tabelle wird beschrieben, wie der Workflow unterschiedlicher AdWords-Objekte gesteuert wird, um einen bestimmten Status zu erreichen:

Typ Neues Objekt hinzufügen Aktivieren Pausieren Entfernen/deaktivieren
Campaign Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: PAUSED
Aktion: mutate()
Vorgang: SET
Status: REMOVED
Budget Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: REMOVED
AdGroup Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: PAUSED
Aktion: mutate()
Vorgang: SET
Status: REMOVED
AdGroupAd Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: PAUSED
Aktion: mutate()
Vorgang: REMOVE
Status: DISABLED
BiddableAdGroupCriterion Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: ENABLED
Aktion: mutate()
Vorgang: SET
Status: PAUSED
Aktion: mutate
Vorgang: REMOVE
Status: REMOVED
UserList Aktion: mutate()
Vorgang: ADD
Status: OPEN
Aktion: mutate()
Vorgang: SET
Status: CLOSED
Feed Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: REMOVE
Status: REMOVED
FeedMapping Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: REMOVE
Status: REMOVED
FeedItem Aktion: mutate
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: REMOVE
Status: REMOVED
CustomerFeed Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: REMOVE
Status: REMOVED
CampaignFeed Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: REMOVE
Status: REMOVED
AdGroupFeed Aktion: mutate()
Vorgang: ADD
Status: ENABLED
Aktion: mutate()
Vorgang: REMOVE
Status: REMOVED

Gleichzeitige Änderungen

Wenn mehrere Nutzer dasselbe Objekt mit Ihrer App aktualisieren oder wenn Sie mehrere AdWords-Objekte mit mehreren Threads ändern, um einen besseren Durchsatz zu erzielen, müssen Sie wissen, wie AdWords gleichzeitige Änderungsanfragen für dasselbe Objekt verarbeitet.

Ein AdWords-Objekt kann nicht gleichzeitig von mehr als einer Quelle geändert werden. Darunter fallen Aktualisierungen des Objekts über mehrere Threads derselben Anwendung oder unterschiedlicher Anwendungen (z. B. Ihre Anwendung und eine gleichzeitig offene AdWords Editor-Sitzung). Die AdWords API stellt keine Möglichkeit zum Sperren von Objekten vor der Aktualisierung bereit: Wenn zwei Quellen versuchen, ein Objekt gleichzeitig zu ändern, gibt die API den Fehler CONCURRENT_MODIFICATION_ERROR zurück.

Weitere Informationen zum Verwalten gleichzeitiger Änderungen mit der AdWords API finden Sie in diesem Blogpost.

Asynchrone im Vergleich zu synchronen "mutate"-Vorgängen

AdWords API-mutate()-Methoden sind synchron: API-Aufrufe geben erst nach dem Ändern von Objekten eine Antwort zurück. Sie müssen daher für jede Anfrage auf die Antwort warten. Dieser Ansatz lässt sich zwar relativ einfach programmieren, er könnte sich jedoch ungünstig auf den Lastenausgleich auswirken und zu Ressourcenvergeudung führen, weil auf den Abschluss eines Aufrufs gewartet werden muss.

Ein alternativer Ansatz besteht darin, die Objekte asynchron mithilfe von BatchJobService zu ändern. Dieser Dienst bietet die Möglichkeit, mehrere Vorgänge für mehrere Dienste auszuführen, ohne auf den Abschluss der jeweiligen Vorgänge warten zu müssen. Sobald der Batch-Auftrag gesendet wurde, führen die AdWords API-Server die Vorgänge asynchron aus. Ihr Computer kann daher andere Vorgänge durchführen. Sie müssen nur noch regelmäßig prüfen, ob der Auftrag abgeschlossen ist.

Im Leitfaden zur Batch-Verarbeitung finden Sie weitere Informationen zur asynchronen Verarbeitung.

mutate-Validierung

Mit dem SOAP-Header validateOnly können Sie Ihre API-Aufrufe testen, ohne Änderungen an den Daten vorzunehmen: Sie können also auf fehlende Parameter und fehlerhafte Feldwerte prüfen, ohne den Vorgang tatsächlich auszuführen.

Um diese Funktion zu nutzen, setzen Sie das Feld validateOnly in RequestHeader auf true. Dieser Wert wird von den Clientbibliotheken standardmäßig auf false gesetzt.

Die Anfrage wird vollständig validiert, als ob sie ausgeführt würde. Die eigentliche Ausführung wird jedoch übersprungen. Wenn keine Fehler gefunden werden, wird eine leere Antwort zurückgegeben. Wenn die Validierung fehlschlägt, geben Fehlermeldungen die Fehlerursachen an.

Hier sehen Sie ein Beispiel, wie validateOnly mithilfe der Java-Bibliothek eingerichtet wird:

Credential oAuth2Credential = new OfflineCredentials.Builder()
    .forApi(Api.ADWORDS)
    .fromFile()
    .build()
    .generateCredential();

AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(oAuth2Credential)
    .build();

session.setValidateOnly(true);

Für alle API-Aufrufe in dieser Sitzung wird der Header validateOnly auf true gesetzt.

Der Header validateOnly ist besonders hilfreich, um Anzeigen auf gängige Richtlinienverstöße zu überprüfen. Anzeigen werden automatisch abgelehnt, wenn sie gegen Richtlinien bezüglich der Verwendung von bestimmten Wörtern, Satzzeichen, Großschreibung oder Länge verstoßen. Wenn Sie Anzeigen in Batches hochladen, kann eine einzige ungültige Anzeige dazu führen, dass die gesamte Batch-Verarbeitung fehlschlägt. Wenn Sie eine neue Anzeige mit validateOnly testen, können Sie einfach feststellen, ob sie abgelehnt würde. Im Codebeispiel zur Behandlung von Fehlern bei Richtlinienverstößen wird dies veranschaulicht.

Wenn Sie keine Clientbibliothek verwenden, müssen Sie lediglich den richtigen SOAP-Header einrichten. Sie können dann trotzdem die mutate()-Anfragen validieren.

AdWords API-Dienste

In diesem Abschnitt werden die von der AdWords API gebotenen Dienste beschrieben. Dabei sind auch Links zu den entsprechenden Referenzseiten mit zusätzlichen Informationen zu jedem Dienst enthalten.

Die AdWords API-Dienste lassen sich in vier Funktionskategorien unterteilen:

Verwaltung von Kampagnendaten

Verwenden Sie die Dienste zur Verwaltung von Kampagnendaten zur Bearbeitung von AdWords-Kampagnen und zugehörigen Elementen. Jeder Dienst zur Verwaltung von Kampagnendaten entspricht einem Element in der Kampagnendatenhierarchie.

Dienst Beschreibung
CampaignService Kampagnen erstellen, aktualisieren und entfernen. In einer Kampagne sind eine oder mehrere Anzeigengruppen enthalten. Für jede Kampagne sind individuelle Einstellungen festgelegt: Budget, Gebotsstrategie, Zeitraum zur Anzeigenauslieferung und Ausrichtung.
AdGroupService Anzeigengruppen erstellen, aktualisieren und entfernen. In einer Anzeigengruppe sind Anzeigen und Kriterien enthalten. Außerdem ist für die Kriterien das Standardgebot festgelegt.
AdGroupAdService Anzeigen erstellen, aktualisieren und entfernen.
CampaignExtensionSettingService Anzeigenerweiterungen erstellen, aktualisieren und entfernen. Mit Anzeigenerweiterungen für Kampagnen werden allen Standardtextanzeigen in einer Kampagne Standortinformationen, zusätzliche Links oder eine Telefonnummer hinzugefügt.
CampaignCriterionService
AdGroupCriterionService
Kriterien erstellen, aktualisieren und entfernen. Ein Kriterium beschreibt die Bedingungen, die festlegen, ob eine Anzeige ausgeliefert werden soll.
ConversionTrackerService
OfflineConversionFeedService
Dieser Dienst misst die Effektivität Ihrer Anzeigen und Keywords, indem ermittelt wird, was passiert, nachdem ein Nutzer auf Ihre Anzeige geklickt hat. Mit OfflineConversionFeedService können Offline-Conversions importiert werden.
DataService Kampagnenverwaltungsdaten auf festgelegten Kriterien basierend abrufen
FeedService
FeedItemService
FeedMappingService
AdGroupFeedService
CampaignFeedService
Benutzerdefinierte Datenfeeds zum Verwalten von Sitelink-, Anruf- und In-App-Link-Erweiterungen erstellen
AdwordsUserListService Nutzerlisten erstellen, aktualisieren und entfernen. Mithilfe von Nutzerlisten und Kriterien für Nutzerlisten werden Anzeigen für Nutzer geschaltet, die auf Ihrer Website bereits eine Conversion durchgeführt haben.
BudgetService Budgets erstellen, aktualisieren und entfernen. Zur Verwaltung von Budgets, die kampagnenübergreifend verwendet werden können.

Optimierung

Mit Optimierungsdiensten rufen Sie Leistungsstatistiken ab und erhalten Ideen für neue Kriterien.

Dienst Beschreibung
ReportDefinitionService Eine Vielzahl von Leistungsberichten erstellen und herunterladen.
TargetingIdeaService Neue Keyword- und Placement-Ideen auf Basis von Parametern generieren, die Sie angeben.
TrafficEstimatorService Zugriffsschätzungen für vorgeschlagene Kampagnen, Anzeigengruppen und Keywords abrufen
DraftService und TrialService Neue Entwürfe und Tests für Ihre Kampagneneinstellungen erstellen. Ausführliche Informationen hierzu finden Sie in diesem Leitfaden.

Kontoverwaltung

Mit Diensten zur Kontoverwaltung behalten Sie Ihre Kontoaktivitäten im Auge.

Dienst Beschreibung
CustomerService Grundlegende Informationen zu einem Kundenkonto abrufen
CustomerSyncService Datensatz mit Änderungen an Kampagnendaten innerhalb eines bestimmten Zeitraums abrufen
ManagedCustomerService Kundenkonten und Verknüpfungen zwischen Verwaltungs- und Kundenkonten verwalten

Zusatzdienst

Mit diesen Zusatzdiensten erledigen Sie diverse nützliche Aufgaben mit der AdWords API.

Dienst Beschreibung
BatchJobService Einen großen Batch-Auftrag mit Kampagnendatenvorgängen asynchron verarbeiten. Batch-Verarbeitungsaufträge dauern länger als synchrone Aufrufe der standardmäßigen Webdienste, bieten jedoch andere Vorteile (siehe Leitfaden zur Batch-Verarbeitung).
MediaService IDs von Medien hochladen und abrufen, die Sie in medienbasierten Anzeigen wie Bild- oder Videoanzeigen verwenden
ConstantDataService Von der API verwendete konstante Werte abrufen
LocationCriterionService ID eines Standortkriteriums abrufen

Kampagnendaten

Die Arbeit mit Kampagnendaten ist eine der grundlegenden Aufgaben, die Sie mit der AdWords API durchführen. In der folgenden Tabelle sind die einzelnen Kampagnendatenelemente und ihre Beziehungen zu anderen Kampagnendaten beschrieben.

Entität
Untergeordnete Elemente (Anzahl)
Datentyp Beschreibung
Kampagne
Anzeigengruppen (1+)
Kampagnenziellisten (7)
Anzeigenerweiterungen für Kampagnen (0+)
Kampagnenkriterien (0+)
Campaign In einer Kampagne sind eine oder mehrere Anzeigengruppen enthalten. Für jede Kampagne sind individuelle Einstellungen festgelegt: Budget, Gebotsstrategie und Zeitraum zur Anzeigenauslieferung.
Anzeigengruppe
Anzeigen (1+)
Kriterien (1+)
AdGroup
In einer Anzeigengruppe sind Anzeigen und Kriterien enthalten. Außerdem ist für die Kriterien das Standardgebot festgelegt.
Anzeige
Überschreibungen durch Anzeigenerweiterung (0+)
AdGroupAd Verfügbare Anzeigentypen sind in der API-Referenz als Unterklassen des abstrakten Typs Ad dokumentiert.
Kriterium
AdGroupCriterion, CampaignCriterion Ein Kriterium beschreibt die Bedingungen, auf deren Grundlage entschieden wird, ob eine Anzeige ausgeliefert werden soll (gebotsfähiges Kriterium) oder nicht (auszuschließendes Kriterium). Ein Anzeigengruppenkriterium wirkt sich auf Anzeigen in der übergeordneten Anzeigengruppe aus. Ein Kampagnenkriterium ist immer ein auszuschließendes Kriterium. Es definiert Bedingungen, mit denen verhindert wird, dass die Anzeigen der Kampagne geschaltet werden.
Anzeigenerweiterung
CampaignExtensionSetting Mit Anzeigenerweiterungen für Kampagnen werden allen Standardtextanzeigen in einer Kampagne Standortinformationen, zusätzliche Links oder eine Telefonnummer hinzugefügt.
Feed
Feed Feeds dienen als "Leitungen" für Daten zu Anzeigenerweiterungen (Sitelink, Anruf, In-App).
Nutzerliste
UserList In Nutzerlisten wird erfasst, welche Nutzer bereits Interesse an Ihrer Website zum Ausdruck gebracht haben. Sie können Anzeigen auf diese Gruppe von Nutzern ausrichten, indem Sie ein Nutzerlistenkriterium erstellen und mit einer vorhandenen Nutzerliste verknüpfen.
Budget
Budget Budgets werden zur Verwaltung der Ausgaben für Kampagnen verwendet. Ein Budget kann für verschiedene Kampagnen eingesetzt werden. Das System ermittelt automatisch die optimale Zuordnung.

Feedback geben zu...