Estrutura de chamada da API

Este guia descreve os elementos de uma chamada de API e demonstra como fazer uma chamada básica usando cURL.

Se você utiliza uma biblioteca cliente ou biblioteca SOAP para interagir com a API, provavelmente não precisará se preocupar com SOAP e XML subjacentes. No entanto, ter conhecimento sobre eles pode ser útil ao realizar testes e depurações.

Fazer chamadas para a API envolve o envio de solicitações HTTPS POST a um serviço e a interpretação da resposta. O corpo de solicitação e resposta inclui o XML definido por um WSDL. É possível imprimir o WSDL anexando um ?wsdl ao URL do serviço:

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

Cabeçalhos de solicitação

Os cabeçalhos HTTP associam-se ao corpo SOAP+XML na solicitação:

Autorização
É necessário incluir um token de acesso OAuth2 no formulário de Authorization : Bearer YOUR_ACCESS_TOKEN que identifica uma conta de administrador agindo em nome de um cliente ou um anunciante gerenciando diretamente a própria conta. Instruções para recuperar um token de acesso estão disponíveis no Guia do OAuth2. O token de acesso é válido por uma hora após sua aquisição. Quando ele expirar, atualize-o para receber um novo. Nossas bibliotecas cliente atualizam automaticamente os tokens expirados.
developerToken
Uma string de 22 caracteres exclusiva que identifica um desenvolvedor da AdWords API. 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 como o nome e a versão do seu aplicativo para nos ajudar a identificar suas solicitações durante o diagnóstico de problemas, por exemplo, example.com:ReportDownloader:V7.18.
clientCustomerId
ID de cliente da conta do Google AdWords segmentada, normalmente no formato 123-456-7890. Necessário em todas as chamadas para todos os serviços, exceto CustomerService e ReportDefinitionService.
validateOnly (opcional)
Se está definido como true, a solicitação está validada, mas não foi realizada. É possível usar esse cabeçalho para validar dados fornecidos pelo usuário.
partialFailure (opcional e disponível somente para alguns serviços)
Se definido como true, o serviço executará todas as operações que não contenham erros e retornará os erros das operações com falha. Esse cabeçalho é ignorado nas operações que não são de modificação.

Cabeçalhos de resposta

Os seguintes cabeçalhos são retornados com o XML de resposta. Recomendamos que esses valores sejam registrados para fins de depuração.

requestId
String 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 chamada de API

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

Solicitação

  1. Providencie o ID de cliente do OAuth2 e a chave secreta do cliente (se ainda não tiver). Siga as instruções no guia do OAuth2.

  2. Providencie um token de acesso do OAuth2. Para solicitar o token de acesso do OAuth2, insira seu ID de cliente do OAuth2 no URL a seguir e cole-o no navegador:

    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

    Uma tela será exibida. Lá, você concederá ao aplicativo o acesso aos seus 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, faça a solicitação de troca do 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 a solicitação de forma adequada, o Google retornará seu token de acesso do OAuth2. O token de acesso (mostrado em negrito após access_token :) é necessário para enviar solicitações aos serviços da AdWords API.

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

  3. 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 marcadores de posição) como 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. Envie a solicitação. Use cURL para enviar essa solicitação SOAP para 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/v201609/CampaignService

Resposta

Depois que o servidor da 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"?>
<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>

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
AdWords API
AdWords API
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.