API-Aufrufstruktur

In diesem Leitfaden werden die Elemente eines API-Aufrufs beschrieben. Außerdem wird gezeigt, wie einfache Aufrufe mithilfe von cURL durchgeführt werden.

Falls Sie eine Clientbibliothek oder eine SOAP-Bibliothek für die Interaktion mit der AdWords API verwenden, müssen Sie sich wahrscheinlich keine Gedanken im Hinblick auf SOAP und XML machen. Kenntnisse von SOAP und XML können sich jedoch bei der Fehlerbehebung mithilfe der AdWords API als nützlich erweisen.

Beim Aufruf der AdWords API werden HTTPS POST-Anfragen an einen Dienst gesendet und die Antwort wird interpretiert. Der Text der Anfrage und der Antwort besteht aus XML-Code, der durch eine WSDL definiert wird. Sie können die WSDL ausgeben, indem Sie an die Dienst-URL ?wsdl anhängen:

https://adwords.google.com/api/adwords/cm/v201609/CampaignService?wsdl

Anfrage-Header

Der SOAP+XML-Text in der Anfrage tritt zusammen mit HTTP-Headern auf:

Authorization
Sie müssen ein OAuth2-Zugriffstoken im Format Authorization : Bearer YOUR_ACCESS_TOKEN einschließen, das entweder ein Verwaltungskonto, das im Namen eines Kunden agiert, oder einen Werbetreibenden identifiziert, der direkt mit sein eigenes Konto. Eine Anleitung zum Abrufen von Zugriffstokens erhalten Sie im OAuth2-Leitfaden. Ein Zugriffstoken ist nach Erhalt eine Stunde lang gültig. Aktualisieren Sie das Zugriffstoken nach Ablauf, um ein neues zu erhalten. Unsere Clientbibliotheken aktualisieren abgelaufene Tokens automatisch.
developerToken
A 22‒character string that uniquely identifies an AdWords API developer. Beispiel für einen Entwickler-Token-String: ABcdeFGH93KL-NOPQ_STUv.
userAgent
Ein benutzerdefinierter String, der den Absender und den Zweck der Anfrage definiert. Setzen Sie diesen auf den Namen Ihrer Anwendung und Version, damit wir Ihre Anfrage bei der Untersuchung eines Problems finden können. Ein Beispiel: example.com:ReportDownloader:V7.18.
clientCustomerId
Kundennummer des betroffenen AdWords-Kontos, in der Regel im Format 123-456-7890. Erforderlich für alle Aufrufe sämtlicher Dienste mit Ausnahme von CustomerService und ReportDefinitionService.
validateOnly (optional)
Wenn dieser Parameter auf true festgelegt ist, wird die Anfrage validiert, aber nicht durchgeführt. Mithilfe des Headers können Sie von Nutzern bereitgestellte Daten validieren.
partialFailure (optional und nur für bestimmte Dienste verfügbar)
Wenn dieser Parameter auf true festgelegt ist, führt der Dienst fehlerfreie Vorgänge aus und gibt für fehlgeschlagene Vorgänge Fehlermeldungen aus. Dieser Header wird für Nicht-Mutate-Vorgänge ignoriert.

Antwort-Header

Die folgenden Header werden im Antwort-XML-Code zurückgegeben. Wir empfehlen, diese Werte zu notieren, um Fehler leichter beheben zu können.

requestId
String, der diese Anfrage eindeutig identifiziert
operations
Anzahl der ausgeführten Vorgänge dieser Anfrage
responseTime
Verstrichene Zeit in Millisekunden vom Eingang der Anfrage beim Webservice bis zur Versendung der Antwort

Beispiel eines API-Aufrufs

Dieses Beispiel zeigt, wie Sie über cURL mit der AdWords API interagieren. cURL und SOAP+XML sind zwar ungeeignet, um eine echte Anwendung zu erstellen, aber es lässt sich damit veranschaulichen, wie die AdWords API auf der untersten Ebene funktioniert.

Anfrage

  1. Rufen Sie die OAuth2-Client-ID und den Clientschlüssel ab (falls noch nicht geschehen). Folgen Sie dazu der Anleitung im OAuth2-Leitfaden.

  2. Rufen Sie ein OAuth2-Zugriffstoken ab. Geben Sie zum Abrufen des Zugriffstokens von OAuth2 die OAuth2-Client-ID in die unten stehende URL ein und fügen Sie diese in Ihrem Browser ein:

    https://accounts.google.com/o/oauth2/auth?client_id=your-client-id&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords&redirect_uri=urn:ietf:wg:oauth:2.0:oob&access_type=offline&prompt=consent
    

    Nun wird ein Bildschirm angezeigt, in dem Sie Ihrer Anwendung Zugriff auf Ihre AdWords-Daten geben können:

    Akzeptieren Sie diese Anfrage. Sie erhalten nun einen Autorisierungscode, den Sie gegen ein Zugriffstoken eintauschen können.

    Fordern Sie damit für den Autorisierungscode ein Zugriffstoken an:

    curl \
      -d code=your-authorization-code \
      -d client_id=your-client-id \
      -d client_secret=your-client-secret \
      -d redirect_uri=urn:ietf:wg:oauth:2.0:oob \
      -d grant_type=authorization_code https://accounts.google.com/o/oauth2/token

    Wenn die Anfrage korrekt formuliert war, erhalten Sie von Google ein OAuth2-Zugriffstoken. Sie benötigen das Zugriffstoken (wird nach access_token : fett angezeigt), um Anfragen an die AdWords API-Dienste zu senden.

    {
      "access_token" : "ya29.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/Ixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }

  3. Erstellen Sie eine SOAP-Anfrage. Der folgende XML-Code definiert eine SOAP-Anfrage zum Hinzufügen eines Budgets. Speichern Sie diesen XML-Code (mit Ihrem Authentifizierungs-Token und den Anmeldedaten Ihres Kontos anstelle der Platzhalter) als hello_world.xml:

    <?xml version="1.0"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Header>
        <ns1:RequestHeader xmlns:ns1="https://adwords.google.com/api/adwords/cm/v201609" soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0">
          <ns1:clientCustomerId>xxx-xxx-xxxx</ns1:clientCustomerId>
          <ns1:developerToken>YOUR_DEVELOPER_TOKEN</ns1:developerToken>
          <ns1:userAgent>YOUR_APPLICATION_NAME</ns1:userAgent>
          <ns1:validateOnly>false</ns1:validateOnly>
          <ns1:partialFailure>false</ns1:partialFailure>
        </ns1:RequestHeader>
      </soapenv:Header>
      <soapenv:Body>
        <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201609">
          <operations>
            <operator>ADD</operator>
            <operand>
              <name>Hello World</name>
              <status>PAUSED</status>
              <budget>
                <budgetId>YOUR_BUDGET_ID</budgetId>
              </budget>
              <settings xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201609" xsi:type="ns2:GeoTargetTypeSetting">
                <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
              </settings>
              <advertisingChannelType>SEARCH</advertisingChannelType>
              <networkSetting>
                <targetGoogleSearch>true</targetGoogleSearch>
                <targetSearchNetwork>true</targetSearchNetwork>
                <targetContentNetwork>false</targetContentNetwork>
              </networkSetting>
              <biddingStrategyConfiguration>
                <biddingScheme xmlns:ns4="https://adwords.google.com/api/adwords/cm/v201609" xsi:type="ns4:ManualCpcBiddingScheme">
                  <enhancedCpcEnabled>false</enhancedCpcEnabled>
                </biddingScheme>
              </biddingStrategyConfiguration>
            </operand>
          </operations>
        </mutate>
      </soapenv:Body>
    </soapenv:Envelope>
    
  4. Senden Sie die Anfrage. Senden Sie diese SOAP-Anfrage mit cURL an CampaignService. Das Zugriffstoken kann dabei wie folgt in den HTTP-Header aufgenommen werden:

    curl --header "Content-Type: application/soap+xml" \
         --header "Authorization : Bearer YOUR_ACCESS_TOKEN" \
         --data @hello_world.xml \
           https://adwords.google.com/api/adwords/cm/v201609/CampaignService

Antwort

Nachdem der AdWords API-Server Ihre Anfrage verarbeitet hat, gibt er eine Antwort mit den XML-Daten für die neu hinzugefügte Kampagne zurück:

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201609">
      <requestId>00053282f54911280ac10da199076e99</requestId>
      <serviceName>CampaignService</serviceName>
      <methodName>mutate</methodName>
      <operations>1</operations>
      <responseTime>269</responseTime>
    </ResponseHeader>
  </soap:Header>
  <soap:Body>
    <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201609">
      <rval>
        <ListReturnValue.Type>CampaignReturnValue</ListReturnValue.Type>
        <value>
          <id>123456789</id>
          <name>Hello World</name>
          <status>PAUSED</status>
          <servingStatus>SUSPENDED</servingStatus>
          <startDate>20160510</startDate>
          <endDate>20371230</endDate>
          <budget>
            <budgetId>YOUR_BUDGET_ID</budgetId>
            <name>...</name>
            <amount>
              <ComparableValue.Type>Money</ComparableValue.Type>
              <microAmount>50000000</microAmount>
            </amount>
            <deliveryMethod>STANDARD</deliveryMethod>
            <isExplicitlyShared>true</isExplicitlyShared>
            <status>ENABLED</status>
          </budget>
          <conversionOptimizerEligibility>
            <eligible>false</eligible>
            <rejectionReasons>NOT_ENOUGH_CONVERSIONS</rejectionReasons>
          </conversionOptimizerEligibility>
          <adServingOptimizationStatus>OPTIMIZE</adServingOptimizationStatus>
          <settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="GeoTargetTypeSetting">
            <Setting.Type>GeoTargetTypeSetting</Setting.Type>
            <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
          </settings>
          <advertisingChannelType>SEARCH</advertisingChannelType>
          <networkSetting>
            <targetGoogleSearch>true</targetGoogleSearch>
            <targetSearchNetwork>true</targetSearchNetwork>
            <targetContentNetwork>false</targetContentNetwork>
            <targetPartnerSearchNetwork>false</targetPartnerSearchNetwork>
          </networkSetting>
          <biddingStrategyConfiguration>
            <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
            <biddingScheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ManualCpcBiddingScheme">
              <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>
              <enhancedCpcEnabled>false</enhancedCpcEnabled>
            </biddingScheme>
          </biddingStrategyConfiguration>
          <campaignTrialType>BASE</campaignTrialType>
          <baseCampaignId>123456789</baseCampaignId>
        </value>
      </rval>
    </mutateResponse>
  </soap:Body>
</soap:Envelope>

Feedback geben zu...