SOAP Primer

Apresentamos a você os parâmetros nos cabeçalhos de resposta e de solicitação SOAP da Google AdWords API e, em seguida, mostramos um exemplo de como fazer uma chamada SOAP com cURL.

Cabeçalhos de solicitação

Cabeçalhos HTTP

Autorização
É necessário incluir um token de acesso do OAuth2 no formato Authorization : Bearer YOUR_ACCESS_TOKEN que identifique um gerente da MCC agindo em nome de um cliente ou um anunciante gerenciando diretamente sua própria conta. Instruções para recuperar um token de acesso estão disponíveis no Guia do OAuth2. Um token de acesso é válido por uma hora após sua aquisição. Quando ele expirar, atualize o token de acesso para recuperar um novo. Nossas bibliotecas cliente atualizam automaticamente tokens expirados.

Cabeçalhos SOAP

Ao enviar uma solicitação a qualquer um dos serviços da Web da Google AdWords API, é necessário fornecer os seguintes cabeçalhos com sua solicitação:

developerToken
Uma cadeia de 22 caracteres que identifica uma Google AdWords API do desenvolvedor. Um exemplo de string de token de desenvolvedor é ABcdeFGH93KL-NOPQ_STUv.
userAgent
Uma string especificada pelo usuário que define o remetente e a finalidade da solicitação. Defina-a para o nome e a versão do seu aplicativo, a fim de nos ajudar a encontrar suas solicitações ao diagnosticar um problema. Exemplo: example.com:ReportDownloader:V7.18
clientCustomerId
Ao agir em nome de um cliente, esse cabeçalho especifica o ID de cliente desse cliente. IDs de cliente geralmente apresentam o formato 123-456-7890.
validateOnly (opcional)
Se for definido como true, a solicitação será validada, mas não executada. Você pode usar esse cabeçalho para validar dados fornecidos pelo usuário.
partialFailure (optional; AdGroupCriterionService, AdGroupAdService; v201206+: AdGroupService, CampaignService, CampaignAdExtensionService, CampaignCriterionService)
Se for definido como true, o serviço realizará operações livres de erros e mostrará os erros das operações com falhas. Esse cabeçalho é ignorado em operações que não são mutate.

Cabeçalhos de resposta

Os seguintes cabeçalhos são retornados com o XML de resposta. Para obter suporte e para fins de depuração, recomendamos que você registre esses valores.

requestId
Sequência de caracteres que identifica exclusivamente esta solicitação.
operations
Número de operações realizadas nesta solicitação.
responseTime
Tempo decorrido em milésimos de segundo entre o serviço da Web que recebe a solicitação e o envio da resposta.

Exemplo de envio SOAP

Este exemplo mostra como interagir com a Google AdWords API usando cURL. Embora não seja prático utilizar cURL e SOAP+XML para criar um aplicativo real, o tutorial demonstra o funcionamento da Google AdWords API no nível mais simples.

  1. 0. Receba seu token de acesso.

    Primeiro, é necessário registrar seu aplicativo usando o Google Developers Console e criar um ID de cliente como um aplicativo instalado. O Google então fornece as informações que serão necessárias posteriormente, como o código e uma chave secreta do cliente.

    Para solicitar seu token de autenticação do OAuth2, cole o URL a seguir no navegador

    https://accounts.google.com/o/oauth2/auth?
    client_id=your-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

    Em seguida, você verá uma tela para conceder ao seu aplicativo acesso aos dados do Google AdWords:

    Depois de aceitar a solicitação, você receberá um código de autorização que pode ser trocado por um token de acesso.

    Por fim, você pode fazer a solicitação para trocar o código de autorização por um token de acesso:

    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

    Se você tiver feito uma solicitação adequada, o Google retornará seu token OAuth2. Você precisa do token de acesso (mostrado em negrito após access_token :) ao enviar solicitações aos serviços da Google AdWords API.

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

  2. 1. Crie uma solicitação SOAP.

    O XML a seguir define uma solicitação SOAP que adiciona um orçamento. Salve esse XML (com seu token de autenticação e o login da sua conta no lugar dos marcador de posição) como hello_world.xml. Se precisar identificar o clientCustomerId, consulte estas instruções.

    <?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>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/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. Envie a solicitação.

    Use cURL para enviar essa solicitação SOAP ao CampaignService. É possível enviar seu token de acesso incluindo-o no cabeçalho HTTP desta maneira:

    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

    Depois que o servidor da Google AdWords API processar sua solicitação, ele retornará uma resposta que contém os dados XML que representam a campanha recém-adicionada:

    <?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>
    

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.