Merge pull request #2 from ProjectPODER/comentarios-formato-docker

Actualización #2

docs/C2/Seccion2.md

@@ -53,7 +53,20 @@ Una vez instalado Docker, nuestro software estará listo para iniciarse automát
 de software auxiliar ni dependencias.
 
 Otra ventaja de usar Docker es que mantiene estabilidad entre lo que se desarrolla y lo que se distribuye, se evitan
-problemas del tipo "surgieron problemas en tu computadora pero en mi computador si funciona".
+problemas del tipo "funciona correctamente en mi computadora".
+
+> En las siguientes secciones utilizaremos diversos comandos de docker, entre los detalles más importantes se encuentra
+> el concepto de "volúmenes" que podriamos entender como "carpetas compartidas" entre el contenedor docker y nuestra computadora.
+    ```
+    docker run -v CARPETA_LOCAL:CARPETA_DEL_CONTENEDOR imagen
+    ```
+    La opción `-v A:B` le indica a docker que queremos compartir la carpeta `A` de nuestra computadora con el contenedor,
+    pero para el contenedor se llamará `B`
+    Un ejemplo:
+    ```
+    docker run -v $HOME/Descargas:/input imagen
+    ```
+    "Comparte" la carpeta Descargas de mi computadora con el contenedor, dentro del contenedor la carpeta se llamará `/input`
 
 Para saber más sobre Contenedores y Docker, se recomiendan las siguientes lecturas:
 - [Amazon Web Services - Qué es Docker?](https://aws.amazon.com/es/docker/)

docs/C2/Seccion3.md

@@ -58,6 +58,8 @@ OCDS por paquetes json** publicado en el sitio
 > Al 2 de Septiembre de 2018 este archivo lleva por nombre `contratacionesabiertas_bulk_paquetes.json.zip` y tiene un
 tamaño de 310.5 MB aproximadamente.
 
+Es importante mencionar que el formato de esta información se conoce en el estándar OCDS como [recordPackages](http://standard.open-contracting.org/latest/en/schema/record_package/) o [paquete de Registros](http://standard.open-contracting.org/latest/es/schema/record_package/); las herramientas y código incluidas en éste manual utilizan este formato, para utilizar alguno otro como *releases* o *releasePackages* o alguna otra estructura no definida por el estándar OCDS serían necesarias modificaciones al código.
+
 > Estos archivos pueden ser bastante grandes en tamaño, es recomendable tener por lo menos 2GB libres de espacio en
 > disco duro antes de continuar.
 
@@ -84,49 +86,10 @@ sistema operativo. La ruta completa a esta carpeta **debería ser**
 
 Al confirmar esto u obtener la ruta completa de la carpeta con los archivos `.json` podemos continuar.
 
-### Descargando datos de la API
-
-Si deseamos trabajar con un conjunto reducido de contratos, o con datos más actualizados, en la siguiente sección
-encontraremos cómo descargar de la API un subconjunto de datos. De lo contrario puede saltear la siguiente sección.
-
-En la sección anterior se explicó cómo descargar el conjunto completo de los datos en OCDS mediante un sólo archivo, en
-esta sección presentamos una alternativa para descargar sólo los contratos que buscamos o contratos más actualizados que
-aún no se hayan publicado en el archivo completo.
-
-Para realizar esta descarga utilizaremos el comando curl y para filtrarlo el comando jq. Ambos deben ser instalados previamente:
-```
-sudo apt-get install curl jq
-```
-
-Para ver la documentación completa de la API se puede revisar la [Guía básica de uso del API](http://transparenciapresupuestaria.gob.mx/work/models/PTP/programas/OpenDataDay/Resultados/Guia%20_uso_API_contrataciones%20_abiertas.pdf)
-donde se detallan las opciones específicas de filtrado. A continuación algunos ejemplos.
-
-Para descargar los últimos 100 procesos de contratación:
-```
-curl https://api.datos.gob.mx/v2/contratacionesabiertas | jq -crM ".results" > contratacionesabiertas_ultimos_100.json
-```
-
-Para descargar los procesos de contratación que involucran a una unidad compradora determinada (limitado a 1000, pero se puede cambiar)
-```
-curl https://api.datos.gob.mx/v2/contratacionesabiertas?records.compiledRelease.parties.name=Servicio%20de%20Administraci%C3%B3n%20Tributaria&pageSize=1000&page=1 | jq -crM ".results"  > contratacionesabiertas_SAT_1000.json
-```
-
-Para comprender mejor el comando, vamos a detallarlo parte por parte:
-* Primero se invoca a curl
-* Luego se incluye la dirección URL base de la API: [https://api.datos.gob.mx/v2/contratacionesabiertas](https://api.datos.gob.mx/v2/contratacionesabiertas)
-* A continuación los parámetros de filtrado: `records.compiledRelease.parties.name` es para filtrar por el valor de ese
-  campo, es decir, el nombre de alguna de las partes del contrato. pageSize implica cuántos resultados devolverá en cada
-  pedido y page permite ir pidiendo las páginas siguientes en caso de que haya más que una.
-* Luego usamos un comando de jq que nos permite extraer sólo la parte de los resultados.
-* Finalmente indicamos que el resultado de la operación debe ser almacenado en un archivo, es importante que este nombre
-  de archivo represente la consulta realizada para simplificar luego el archivado.
-
-> Estos archivos deben almacenarse y tratarse de la misma forma que en la sección anterior, poniéndolos en la carpeta de
-> descargas, para poder continuar con el próximo paso.
-
 ## Procesando y cargando los datos
 
-**IMPORTANTE** **El proceso actual carga específicamente el dato `compiledRelease` de cada documento OCDS, esto en
+### IMPORTANTE
+**El proceso actual carga específicamente la parte `compiledRelease` de cada documento OCDS, esto en
 función de poder realizar el análisis sobre la ultima versión disponible de los *releases* OCDS, se recomienda leer los
 capítulos anteriores antes de proceder**
 
@@ -163,3 +126,67 @@ Ahora podremos visitar la pagina de [Kibana](http://localhost:5601/app/kibana) y
 
 Para conocer más sobre los detalles técnicos de como logramos hacer la carga de los datos, en la siguiente sección
 hablaremos de como utilizamos LogStash para este proceso.
+
+### Extra: Descargando los datos OCDS directo de la API de datos.gob.mx
+
+Anteriormente se explicó cómo descargar el conjunto completo de los datos en OCDS mediante un sólo archivo, en esta
+sección presentamos una alternativa para descargar sólo los contratos que buscamos o contratos más actualizados que aún
+no se hayan publicado en el archivo completo, para esto usaremos la API datos.gob.mx proporcionada por el gobierno Mexicano.
+
+> Para ver la documentación completa de la API se puede revisar la [Guía básica de uso del API](http://transparenciapresupuestaria.gob.mx/work/models/PTP/programas/OpenDataDay/Resultados/Guia%20_uso_API_contrataciones%20_abiertas.pdf)
+> donde se detallan las opciones específicas de filtrado.
+
+Para realizar la accion de descarga y para manipular un poco los datos utilizaremos las herramientas: [cURL](https://es.wikipedia.org/wiki/CURL)
+y [jq](https://es.wikipedia.org/wiki/Jq).
+
+> El comando `curl` nos permitirá descargar la informacion de forma automatica mientras el comando `jq` nos ayudará a
+> darle un formato manejable a los datos JSON.
+> Más adelante en este manual se incluye una breve introducción a `jq`.
+
+--- 
+Se pueden instalar ambos programas de forma local, por ejemplo para Linux Ubuntu con una instrucción como:
+```
+sudo apt-get install -y curl jq
+```
+Para Windows o Mac, tendriamos que descargar los archivos ejecutables por separado, pero tambien tenemos la opción de usar el
+*contenedor docker* incluido en el presente código, para ello solo tenemos que ejecutar el siguiente comando de docker:
+```
+docker run --rm -it -v $HOME/Descargas:/input --entrypoint=bash logstash-sfp-compranet-ocds
+```
+> Recuerda que `$HOME/` es una abreviación propia de sistemas Linux y Mac, en Windows usaremos `%HOMEPATH%\`
+
+Al ejecutar éste comando obtendremos una nueva línea de comandos, que debe lucir como:
+```
+bash-4.2$
+```
+En esta [línea de comando]((https://es.wikipedia.org/wiki/Bash) ya podremos ejecutar los comandos presentados a continuación.
+
+---
+
+Para descargar los últimos 100 procesos de contratación y guardarlo en un archivo `.json`:
+```
+curl https://api.datos.gob.mx/v2/contratacionesabiertas | jq -crM ".results" > contratacionesabiertas_ultimos_100.json
+```
+
+> Hay que considerar que para conservar los archivos creados dentro del contenedor deberemos moverlos o crearlos en las
+> carpetas compartidas entre la computadora y el contenedor. De lo contrario, estos archivos se perderán al momento de
+> "apagar" el contenedor.
+
+Para descargar los procesos de contratación que involucran a una unidad compradora determinada (limitado a 1000, pero se puede cambiar)
+```
+curl https://api.datos.gob.mx/v2/contratacionesabiertas?records.compiledRelease.parties.name=Servicio%20de%20Administraci%C3%B3n%20Tributaria&pageSize=1000&page=1 | jq -crM ".results"  > contratacionesabiertas_SAT_1000.json
+```
+
+Para comprender mejor este último comando, vamos a detallarlo parte por parte:
+* Primero se invoca a `curl`
+* Luego se incluye la dirección URL base de la API: [https://api.datos.gob.mx/v2/contratacionesabiertas](https://api.datos.gob.mx/v2/contratacionesabiertas)
+* A continuación los parámetros de filtrado:
+    - `records.compiledRelease.parties.name`: filtra por el valor de ese campo, es decir, el nombre de alguna de las partes del contrato.
+    - `pageSize`: especifica cuántos resultados devolverá en cada pedido
+    - `page`: permite ir pidiendo las páginas siguientes en caso de que haya más de una.
+* Luego usamos el comando `jq` para extraer únicamente la parte de los resultados.
+* Finalmente indicamos que el resultado de la operación debe ser almacenado en un archivo, es importante que este nombre
+  de archivo represente la consulta realizada para simplificar luego el archivado.
+
+> Estos archivos deben almacenarse y tratarse de la misma forma que en la sección anterior, poniéndolos en la carpeta de
+> descargas, para poder continuar con el próximo paso.