SOAP Primer

In diesem Artikel stellen wir Ihnen die Parameter der AdWords API SOAP-Anfrage- und Antwort-Header vor. Außerdem zeigen wir Ihnen einen Beispiel-SOAP-Aufruf mit cURL.

Anfrage-Header

HTTP-Header

Autorisierung
Sie müssen ein OAuth2-Zugriffstoken in der Form Authorization: Bearer YOUR_ACCESS_TOKEN aufnehmen, das entweder den Kundencenter-Manager, der für den Kunden handelt, oder einen Werbetreibenden identifiziert, der sein eigenes Konto direkt verwaltet. Eine Anleitung zum Abrufen von Zugriffstokens erhalten Sie im OAuth2-Leitfaden. Zugriffstoken sind nach Erhalt eine Stunde lang gültig. Aktualisieren Sie das Zugriffstoken nach Ablauf, um ein neues zu erhalten. (Unsere Client-Bibliotheken aktualisieren abgelaufene Token automatisch.)

SOAP-Header

Wenn Sie eine Anfrage an einen der AdWords API-Webservices senden, muss Ihre Anfrage die folgenden Header enthalten:

developerToken
Ein 22 Zeichen langer String, der einen AdWords-API-Entwickler eindeutig identifiziert. Beispiel für einen Entwickler-Token-String:ABcdeFGH93KL-NOPQ_STUv.
userAgent
Ein benutzerdefinierter String, der den Sender und Zweck der Anfrage definiert. Geben Sie hier den Namen und die Version Ihrer Anwendung an, damit wir Ihre Anfragen bei der Problemdiagnose schneller finden können. Beispiel: ihremusterdomain.de:ReportDownloader:V7.18
clientCustomerId
Wenn Sie im Auftrag eines Kunden handeln, gibt dieser Header die Kunden-ID des Kunden in folgender Form an: 123-456-7890.
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; AdGroupCriterionService, AdGroupAdService; v201206 und höher: AdGroupService, CampaignService, CampaignAdExtensionService, CampaignCriterionService)
Wenn dieser Parameter auf true festgelegt ist, führt der Service fehlerfreie Vorgänge aus und gibt die Fehler der fehlgeschlagenen Vorgänge zurück. Dieser Header wird für Vorgänge, die keine "mutate"-Vorgänge sind, ignoriert.

Antwort-Header

Die folgenden Header werden mit der Antwort-XML zurückgegeben. Sie sollten diese Werte am besten für Support- und Debugging-Zwecke protokollieren.

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 für eine SOAP-Anfrage

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

  1. 0. Zugriffstoken abrufen

    Sie müssen Ihre Anwendung zunächst mit der Google Developers Console registrieren und eine Client-ID für eine installierte Anwendung erstellen. Von Google werden dann Informationen bereitgestellt, die Sie später benötigen, beispielsweise eine Client-ID und ein Client-Schlüssel.

    Fügen Sie die folgende URL in Ihren Browser ein, um Ihr Authentifizierungstoken von OAuth2 anzufordern.

    https://accounts.google.com/o/oauth2/auth?
    client_id=Ihre-Client-ID&\
    response_type=code&\
    scope=https%3A%2F%2Fadwords.google.com%2Fapi%2Fadwords%2F&\
    redirect_uri=urn:ietf:wg:oauth:2.0:oob&\
    access_type=offline&\
    approval_prompt=auto

    Daraufhin wird eine Seite angezeigt, auf der Ihrer Anwendung Zugriff auf Ihre AdWords-Daten gewährt wird.

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

    Fordern Sie nun für den Autorisierungscode ein Zugriffstoken an.

    curl \
          -d code=Ihr-Zugriffscode\
          -d client_id=Ihre-Client-Id\
          -d client_secret=Ihr-Client-Schlüssel\
          -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 wurde, erhalten Sie von Google ein OAuth2-Token. 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"
    }

  2. 1. SOAP-Anfrage erstellen

    Der folgende XML-Code definiert eine SOAP-Anfrage zum Hinzufügen eines Budgets. Speichern Sie diesen XML-Code (mit Ihrem Authentifizierungstoken und den Anmeldedaten Ihres Kontos anstelle der Platzhalter) als hello_world.xml. Falls Sie die clientCustomerId angeben müssen, befolgen Sie diese Anleitung.

    <?xml version="1.0" encoding="UTF-8"?>
    <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 soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="https://adwords.google.com/api/adwords/cm/v201506">
          <ns1:clientCustomerId>xxx-xxx-xxxx</ns1:clientCustomerId>
          <ns1:developerToken>IHR_ENTWICKLERTOKEN</ns1:developerToken>
          <ns1:userAgent>IHR_ANWENDUNGSNAME</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/v201506">
          <operations>
            <operator>ADD</operator>
            <operand>
              <name>Hello World</name>
              <status>PAUSED</status>
              <budget>
                <budgetId>987654321</budgetId>
              </budget>
              <settings xsi:type="ns2:GeoTargetTypeSetting" xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201506">
                <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
              </settings>
              <settings xsi:type="ns3:KeywordMatchSetting" xmlns:ns3="https://adwords.google.com/api/adwords/cm/v201506">
                <optIn>false</optIn>
              </settings>
              <networkSetting>
                <targetGoogleSearch>true</targetGoogleSearch>
                <targetSearchNetwork>true</targetSearchNetwork>
                <targetContentNetwork>false</targetContentNetwork>
              </networkSetting>
              <biddingStrategyConfiguration>
                <biddingScheme xsi:type="ns4:ManualCpcBiddingScheme" xmlns:ns4="https://adwords.google.com/api/adwords/cm/v201506">
                  <enhancedCpcEnabled>false</enhancedCpcEnabled>
                </biddingScheme>
              </biddingStrategyConfiguration>
            </operand>
          </operations>
        </mutate>
      </soapenv:Body>
    </soapenv:Envelope>
    
  3. 2. Anfrage senden

    Senden Sie mit cURL diese SOAP-Anfrage an CampaignService. Senden Sie Ihr Zugriffstoken wie folgt im HTTP-Header:

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

    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" encoding="UTF-8"?>
      <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Header>
          <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201506">
            <requestId>0004e93c496104180a42fee300007f7d</requestId>
            <serviceName>CampaignService</serviceName>
            <methodName>mutate</methodName>
            <operations>0</operations>
            <responseTime>602</responseTime>
          </ResponseHeader>
        </soap:Header>
        <soap:Body>
          <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201506">
            <rval>
              <ListReturnValue.Type>CampaignReturnValue</ListReturnValue.Type>
              <value>
                <id>123456789</id>
                <name>Hello World</name>
                <status>PAUSED</status>
                <servingStatus>SUSPENDED</servingStatus>
                <startDate>20131021</startDate>
                <endDate>20371230</endDate>
                <budget>
                  <budgetId>987654321</budgetId>
                  <name>Interplanetary Budget #1382345043485</name>
                  <period>DAILY</period>
                  <amount>
                    <ComparableValue.Type>Money</ComparableValue.Type>
                    <microAmount>50000000</microAmount>
                  </amount>
                  <deliveryMethod>STANDARD</deliveryMethod>
                  <isExplicitlyShared>true</isExplicitlyShared>
                  <status>ACTIVE</status>
                </budget>
                <conversionOptimizerEligibility>
                  <eligible>false</eligible>
                  <rejectionReasons>CAMPAIGN_IS_NOT_ACTIVE</rejectionReasons>
                  <rejectionReasons>CONVERSION_TRACKING_NOT_ENABLED</rejectionReasons>
                </conversionOptimizerEligibility>
                <adServingOptimizationStatus>OPTIMIZE</adServingOptimizationStatus>
                <settings xsi:type="KeywordMatchSetting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <Setting.Type>KeywordMatchSetting</Setting.Type>
                  <optIn>false</optIn>
                </settings>
                <settings xsi:type="GeoTargetTypeSetting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <Setting.Type>GeoTargetTypeSetting</Setting.Type>
                  <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
                </settings>
                <networkSetting>
                  <targetGoogleSearch>true</targetGoogleSearch>
                  <targetSearchNetwork>true</targetSearchNetwork>
                  <targetContentNetwork>false</targetContentNetwork>
                </networkSetting>
                <biddingStrategyConfiguration>
                  <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
                  <biddingScheme xsi:type="ManualCpcBiddingScheme" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>
                    <enhancedCpcEnabled>false</enhancedCpcEnabled>
                  </biddingScheme>
                </biddingStrategyConfiguration>
              </value>
            </rval>
          </mutateResponse>
        </soap:Body>
      </soap:Envelope>
    

Feedback geben zu...