Oct 222013
 

En un artículo anterior hemos explicado cómo obtener un token de acceso para solicitar un informe “ad hoc” de adwords.

En este artículo detallamos los tipos de informes que se pueden obtener, y la manera de generar el “report definition” en el que se especifica el tipo de informe solicitado.

Establecer la conexión con el servidor de Google

En el siguiente ejemplo en lenguaje Perl vemos como preparar la conexión con el servidor. Para ello, creamos una instancia de la clase LWP::UserAgent, y añadimos al header el token de acceso (Bearer), el token de desarrollador y el identificador de cliente:

  my $lwp = LWP::UserAgent->new();
  $lwp->agent($client->get_user_agent());

  $lwp->default_header(
      "Authorization" => "Bearer " . $client->get_oauth_2_handler()->get_access_token());
  $lwp->default_header("returnMoneyInMicros" => "true");
  $lwp->default_header("developerToken" => $dev_token);
  $lwp->default_header("clientCustomerId" => $client->get_client_id());

A continuación, realizamos una solicitud POST al servidor de Google Adwords, añadiendo un parámetro “__rdxml” cuyo valor es un documento XML (report definition) que especifica el informe que queremos obtener:

  # Construir la url para la descarga del informe
  my $server = "https://adwords.google.com";
  my $url = sprintf("%s/api/adwords/reportdownload/v201306", $server);
  my $respuesta = $lwp->request(POST $url, [ __rdxml => $rd_xml ]);
  my $informe;
  if ($respuesta->is_success()) {
    $informe = $respuesta->content();
  } else {
    warn(sprintf("La descarga del informe ha fallado con el código \"%d\" y mensaje \"%s\".",
                 $respuesta->code, $respuesta->message));
  }

Sintaxis del parámetro “report definition”

El valor concreto del parámetro __rdxml que añadimos a la solicitud POST depende del tipo de informe que queremos obtener.

Los tipos de informe posibles están documentados en (1) Report Types – AdWords API.

Muchos de ellos son informes de rendimiento a distintos niveles:

    • Account Performance
    • Campaign Performance
    • Adgroup Performance
    • Ad Performance
    • Keyword Performance

En general la estructura del report definition es de la forma:

<reportDefinition>
    <selector>
      <fields>...</fields>
      <fields>...</fields>
      <fields>...</fields>
      <predicates>
        <field>...</field>
        <operator>...</operator>
        <values>...</values>
        <values>...</values>
      </predicates>
      <predicates>
        ...
      </predicates>
      <dateRange>" .
          <min>...</min>
          <max>...</max>
      </dateRange>
    </selector>
    <reportName>NOMBRE_DEL_INFORME</reportName>
    <reportType>TIPO_DE_INFORME</reportType>
    <dateRangeType>CUSTOM_DATE</dateRangeType>
    <downloadFormat>XML</downloadFormat>
    <includeZeroImpressions>false</includeZeroImpressions>
  </reportDefinition>

Hay un documento XSD (XML Schema Definition) que contiene la especificación del contenido válido en una report definition. El documento XSD está accesible en la url:

(2) https://adwords.google.com/api/adwords/reportdownload/v201309/reportDefinition.xsd

Ejemplo:

Supongamos que queremos descargar un informe de rendimiento a nivel de anuncio (AD_PERFORMANCE_REPORT). Los campos disponibles para este tipo de informe están documentados en (1). De entre ellos, nos interesa obtener los identificadores de campaña, adgroup y ad, y los totales de impresiones y clicks, y el coste. Adicionalmente, queremos obtener el Headline del anuncio. Para ello, comenzamos la especificación del report definition con la relación de campos a obtener:

<reportDefinition>
    <selector>
      <fields>CampaignId</fields>
      <fields>AdGroupId</fields>
      <fields>Id</fields>
      <fields>Headline</fields>
      <fields>Impressions</fields>
      <fields>Clicks</fields>
      <fields>Cost</fields>

A continuación, vamos a especificar los criterios de selección de anuncios que queremos que aparezcan en el informe. Esto lo hacemos dentro de uno o varios bloques “<predicates>…</predicates>”. En nuestro caso, queremos obtener un informe de anuncios correspondientes a adgroups que se encuentren en estado ENABLED o PAUSED. Para ello, añadimos al report definition:

      <predicates>
        <field>Status</field>
        <operator>IN</operator>
        <values>ENABLED</values>
        <values>PAUSED</values>
      </predicates>

Consultando el XSD, vemos que podemos utilizar una serie de operadores para valores de tipo string (“IN”, “NOT_IN”, “STARTS_WITH”, “CONTAINS”,…), así como operadores para valores de tipo numérico (“EQUALS”, “GREATER_THAN”, “LESS_THAN”,…)

Así, si queremos limitar el informe a aquellos anuncios que han tenido entre 100 y 1000 impresiones, podemos añadir otros dos predicados:

<predicates>
    <field>Impressions</field>
    <operator>GREATER_THAN_EQUALS</operator>
    <values>100</values>
</predicates>
<predicates>
    <field>Impressions</field>
    <operator>LESS_THAN</operator>
    <values>1000</values>
</predicates>

Antes de cerrar el bloque “<selector>”, añadimos la especificación de las fechas inicial y final a las que se aplica el informe. Por ejemplo:

      <dateRange>
          <min>2013-09-01</min>
          <max>2013-09-30</max>
      </dateRange>
    </selector>

Por último, cerramos el informe especificando un nombre, el tipo de informe, el formato deseado y otros parámetros:

    <reportName>Custom Ad Performance Report</reportName>
    <reportType>AD_PERFORMANCE_REPORT</reportType>
    <dateRangeType>CUSTOM_DATE</dateRangeType>
    <downloadFormat>XML</downloadFormat>
    <includeZeroImpressions>false</includeZeroImpressions>
  </reportDefinition>

El campo <dateRangeType> admite los valores “TODAY”, “YESTERDAY”, “LAST_WEEK”, etc. En este caso, no es necesario especificar el bloque <dateRange> en el interior del bloque <selector>.

En el campo <downloadFormat> podemos especificar el formato de salida como “XML”, “CSV”, “CSVFOREXCEL”, “TSV”, y formatos comprimidos “GZIPPED_XML” y “GZIPPED_CSV”.

 Publicado por en 11:48 am

 Deja un comentario

(requerido)

(requerido)