Oct 032013
 
Artículo Perl

Este artículo presenta un ejemplo de código perl para la descarga de un informe “ad hoc” de adwords, utilizando el procedimiento de autentificación OAuth2 recomendado por Google.

El ejemplo hace uso de la librería perl de acceso al API de adwords que Google pone a disposición de los desarrolladores.

Cómo solicitar un informe “ad hoc” – ClientLogin y OAuth2

El procedimiento para solicitar un informe “ad hoc” de adwords es realizar una solicitud HTTP POST a la url:

(Nota: v201306 es la versión del API de Google AdWords más reciente en el momento de escribir este artículo, y deberá ser sustituido por la versión más reciente en el momento de implementar el procedimiento que se describe en el mismo)

En el cuerpo de la solicitud se envía un argumento “__rdxml”, cuyo valor es un documento XML que contiene una “reportDefinition”.

Este artículo no trata la manera de generar el reportDefinition. Para ello, se puede consultar la documentación oficial:

Además, en el header de la solicitud HTTP se añade la autentificación.

Históricamente, se ha utilizado un procedimiento “ClientLogin”, por el cual la aplicación obtiene un “token” AUTH_TOKEN que se incluye en el header HTTP, de la forma:

El procedimiento ClientLogin está actualmente obsoleto. En su lugar, Google recomienda utilizar el procedimiento OAuth2, por el cual se obtiene un “access token” ACCESS_TOKEN, que se incluye en el header de la solicitud HTTP de la forma:

Para obtener el access token, la aplicación debe validarse en Google, para lo cual debe ser dada de alta previamente en la consola del API de Google, como se explica en el siguiente apartado.

Dar de alta una aplicación en el API de Google

Para dar de alta una aplicación de manera que utilice el procedimiento de autentificación OAuth2, accedemos a la url:

Tras validarnos con una cuenta de Google, accedemos a la página principal, en la que hay un botón para la creación de una validación OAuth2:

oauth2-crear-client-id

 

Al pulsar el botón, aparece un cuadro de diálogo que solicita la introducción de un nombre para la aplicación, y opcionalmente un logo. También hay un campo “Home Page URL”, que podemos dejar en blanco para los efectos de este ejemplo:

oauth2-client-id-form-1

Al pulsar “Next”, aparece un segundo formulario en el que podemos seleccionar el tipo de aplicación que vamos a dar de alta.

En él, seleccionamos “Application type: Installed application”, y “Installed application type: Other”:

oauth2-client-id-form-2

 

Por último, al pulsar sobre el botón “Create client ID”, regresamos a la pantalla principal de la consola del API, en la cual podemos ver los “tokens” client ID y client secret de la identificación de cliente OAuth2 que ha sido creada:

oauth2-tokens

Una vez obtenidos estos tokens, podemos crear el script perl para la descarga de los informes de adwords.

Descarga e instalación de la librería perl de acceso al API de AdWords

Para descargar la librería, accedemos a la url:

http://code.google.com/p/google-api-adwords-perl/

y descargamos el fichero awapi_perl_lib_2_11_0.tar.gz, que es la versión más reciente de la librería en el momento de escribir este artículo.

Tras realizar la descarga, descomprimimos el fichero y realizamos la instalación como se explica en el documento README que contiene.

Obtención de un access token “offline”

En el mecanismo standard de OAuth2 se obtienen access token “online”. Esto significa que los accesos requieren la participación de un usuario que concede a la aplicación el permiso de acceso.

Afortunadamente, también es posible obtener un access token “offline”. En el proceso de obtención de un access token “offline” también es necesario conceder el permiso de acceso a través de una página web, pero una vez obtenido, la aplicación puede guardarlo y seguir utilizándolo indefinidamente, en tanto no se revoque explícitamente el acceso.

Para obtener el access token, vamos al subdirectorio “GOOGLE-ADWORDS-PERL-CLIENT-2.11.0/examples/oauth” de la librería perl que hemos instalado, y ejecutamos el script “generate_offline_credentials.pl”.

El script lee el client id y client secret que hemos obtenido previamente, y a continuación solicita que accedamos a una url para obtener un código de autorización:

 

En dicha url se encuentra la pantalla en la que se concede autorización a la aplicación para acceder al API de AdWords:

oauth2-grant-access

Al pulsar sobre el botón “Accept”, se presenta en pantalla un código de autorización. Copiamos el código y lo pegamos en la ventana en la que estamos ejecutando el script:

Tras pulsar “Enter”, el script finaliza, presentandonos dos opciones para utilizar los códigos de acceso:

Como vemos, los códigos se pueden incluir en el fichero “adwords.properties” que se encuentra en el directorio de login del usuario, o bien se pueden especificar en el interior del script.

Validación de usuario en el script perl

Para comenzar a trabajar con el API, el primer paso es obtener un objeto “client”. Esto lo hacemos con el siguiente código:

En donde previamente hemos inicializado las variables $CLIENT_ID, $OAUTH2_CLIENT_ID, etc.

No se debe confundir la variable $CLIENT_ID, que identifica el cliente adwords sobre el que se va a trabajar, con la variable $OAUTH2_CLIENT_ID, que identifica la aplicación que está obteniendo un permiso de acceso.

Generación de la url para la descarga del report

Como comentábamos al comienzo del artículo, la descarga del ad hoc report requiere la obtención de un “access token” que debemos incorporar al header HTTP de la solicitud.

Tras haber obtenido el objeto $client, ya estamos finalmente en condiciones de obtener el access token, y añadirlo al header HTTP junto con el resto de parámetros requeridos, con el siguiente código:

 Publicado por en 5:07 pm

 Deja un comentario

(requerido)

(requerido)