Cómo trabajar con las plantillas para definir la salida de los métodos

Resumen

Las plantillas de salida o output permiten definir cómo será la respuesta entregada al ejecutar un método de la API.

Las plantillas se relacionan a formatos de salida.

---

Configurar plantillas

Para definir una nueva salida seleccione el formato deseado y Nueva plantilla. También podrá seleccionar una plantilla existente y copiarla para reutilizarla en su nuevo método.

Las plantillas de salida se definen mediante código de jinja templates.

Crear plantilla

Haga clic en el botón Crear plantilla. Se abrirá una ventana donde podrá comenzar a diseñar su plantilla.

En la misma ventana, al crear o editar plantilla, podrá acceder a las referencias que le permitirán invocar los resultados de su vista de datos.

Editar plantilla

Para editar una plantilla, seleccione la plantilla deseada y haga clic en el botón Editar plantilla.

Si la plantilla está siendo utilizada por otro método se mostrará esta ventana. Si hace clic sobre el botón Editar, editará la plantilla y afectará a todos los métodos que la utilicen. También puede crear una copia de la plantilla para el método o para todos los métodos que la utilicen

Luego, se motrará la ventana para editar la plantila.

Borrar plantilla

Si desea eliminar una plantilla, debe seleccionarla y hacer clic en el botón Eliminar plantilla. Al hacerlo, deberá confirmar la operación.

Ayudas sobre las plantillas

A continuación algunas ayudas útiles en la definición de las plantillas.

Si ya tiene algunas plantillas en su cuenta, lo más fácil es tomar una de referencia, duplicarla y hacer las modificaciones que requiera para su método.

Veamos un ejemplo. El objetivo es crear un método a partir de esta vista de datos y realizar algunas transformaciones y configuraciones específicas en la salida del método.

Mediante la siguiente plantilla, se aplican algunas transformaciones para que la salida de nuestro método sea correcta.

{
  "lugares": [
  {% for row in result.data %}
    {  "boundingbox": {{ row.0 | tojson }},
       "class": "{{ row.1 }}",
        {%if row.2 |length %}"icon": "{{ row.2 }}" {% else %}"icon": null{% endif %},
       "displayName": "{{ row.3 }}",
       "importance": {{ row.4 | float }},
       "latitud": {{ row.5 | float }},
       "longitud": {{ row.7 | float }},
       "osmId": {{ row.8 | int }},
       "osmType": "{{ row.9 }}",
       "placeId": {{ row.10 | int }},
       "type": "{{ row.11 }}"
        }{% if not loop.last %},{% endif %}
     {% endfor %}
    ],
    "columns": {{ result.cols}},
    "timestamp": {{ result.timestamp}}
}

Mediante [ {% for row in result.data %} abrimos un loop que recorrerá todas las filas de la vista de datos para entregar los valores de cada una en un objeto dentro de un array.

El loop se cierra mediante }{% if not loop.last %},{% endif %}  {% endfor %}  ],

Mediante row.#
referenciamos la columna de cada una de las filas. Por ejemplo, row.0 imprimirá los valores de la primer columna de la vista de datos. De esa manera podemos definir los atributos de la respuesta y el valor correspondiente.

En el caso de "boundingbox": {{ row.0 | tojson }} indicamos que el valor de la primer columna de nuestra vista debe imprimirse como un JSON. En este caso, previamente definimos el formato de la columna como JSON.

En el caso de  {%if row.2 |length %}"icon": "{{ row.2 }}" {% else %}"icon": null{% endif %},  estamos idicando que si no se encuentran valores en una celda, es decir, la celda está vacía, se imprima como valor null.

En el caso de  "importance": {{ row.4 | float }}, estamos indicando que el valor de la columna es de coma flotante.

En el caso de   "placeId": {{ row.10 | int }}, estamos indicando que el valor de la columna es un entero.

Luego, con   "columns": {{result.cols}}, imprimimos la cantidad de columnas o atributos de la respuesta.

Con  "timestamp": {{result.timestamp}} se indicará el momento de ejecución de la solicitud en formato Unix Epoch.

Filtros jinjaa

En los ejemplos anteriores se mostró la aplicación de filtros jinjaa en base un ejemplo de vista de datos.

Se detallan a continuación otros filtros de utilidad.

Filtro	Descripción	Ejemplo
int	Convierte el valor a número entero. Debe ingresarse sin comillas.	"atributo": {{ row.0 | int }}
float	Convierte el valor a número de coma flotante (valores con decimales). Debe ingresarse sin comillas.	"atributo": {{ row.0 | int }}
replace	Permite reemplazar valores. En el ejemplo, reemplazamos el valor "created" por "creado"	"atributo": "{{ row.0 | replace ('created','creado')}}"
tojson	Permite formatear como json. Requiere que en la vista de datos se haya definido ese formato sobre la columa. Debe ingresarse sin comillas.	"atributo": {{ row.0 | tojson }}
jso nify	Es una forma alternativa al filtro "tojson".	"atributo": {{ row.0 | jsonify }}
upper	Permite convertir a mayúsculas un strint/texto.	"atributo": "{{ row.0 | upper }}"
lower	Permite convertir a minúsculas un strint/texto.	"atributo": "{{ row.0 | lower }}"
trim	Permite eliminar los espacios vacíos al comienzo y final de un string/texto	"atributo": "{{ row.0 | trim }}"

Para más información sobre filtros puede consultar la documentación oficial.

Operaciones jinjaa

Las plantillas permitén, además de lo indicado previamente, realizar operaciones más coplejas.

Por ejemplo, en el siguiente caso se establece que si el valor de la segunda columna es "409" debe imprimirse una respuesta, si es otro valor la respuesta que se imprime es diferente.

{
    "apiVersion": "1.0",
    "prevencionDeRiesgos": {
        "documento": "Informe de Prevención de Riesgos",
        {% if "409" in result.data.0.1 %}
            "mensaje": "El registro ya existe",
            "error": "409"
        {% else %}
            "mensaje": "{{ result.data.0.4 }}",
            "id": {{ result.data.0.2 | int }}
        {% endif %}
    }
}

En este caso {% if "409" in result.data.0.1 %} buscará el valor " 409" en la segunda columna de la primera fila. En caso de encontrar ese valor, imprimirá como respuesta:

{
    "apiVersion": "1.0",
    "prevencionDeRiesgos": {
        "documento": "Informe de Prevención de Riesgos",
            "mensaje": "El registro ya existe",
            "error": "409"
    }
}

Al definir  {% else %}, si no se encuentra el valor definido la respuesta será:

{
    "apiVersion": "1.0",
    "prevencionDeRiesgos": {
        "documento": "Informe de Prevención de Riesgos",
            "mensaje": "{{ result.data.0.4 }}",
            "id": {{ result.data.0.2 | int }}
    }
}

Donde "mensaje": "{{ result.data.0.4 }}", imprimirá el valor de la quinta columna y la primera fila, y "id": {{ result.data.0.2 | int }} imprimirá el valor de la tercer columna y la primera fila, convirtiéndolo a entero.

Este caso puede aplicar en una API de escritura, donde el origen de los datos responde con un código exitoso (Código HTTP 200) pero una respuesta que indica que el documento que se intenta crear ya existe (de ahí el contenido "409" en el valr de una columna)

Las plantillas son muy versátiles para definir las salidas de sus métodos. Si tiene alguna duda contáctenos para que podamos ayudarlo.

• Related Articles

• Cómo definir formatos de respuesta de los métodos

  Resumen Los formatos de salida permiten definir uno o más formatos de respuesta en los métodos de su API. Los formatos de salida pueden ser mútiples en formato JSON, aunque también puede exponer los datos en CSV y XML. Configurar formatos Al crear un ...

• Cómo definir respuestas de error personalizadas

  Resumen Así como puedes definir formatos y plantillas para las respuestas exitosas de la solicitud al método, puedes definir plantillas de error para cada formato que hayas agregado y para cada tipo de error conocido. Configurar plantillas de error ...

• Cómo definir las rutas a los métodos: buenas prácticas

  Resumen La definición de rutas o paths debe ser consistente con los recursos o entidades a los que refiere el método. A continuación se indican ciertas buenas prácticas para considerar en la definición de rutas. Un repaso Antes de continuar, ...

• Qué es una vista de datos

  Resumen La plataforma no requiere de un proceso ETL off-line para extraer los datos desde los orígenes, sino que asociadas a la vista se encuentran un conjunto de reglas que el motor de datos interpreta para consultar la fuente a demanda o ...

• Crear métodos de APIs

  Resumen En el articulo Crear y gestionar versiones de APIs se mostraron los primeros pasos necearios para crear APIs. Los métodos definen la acción que se realizará sobre un determinado recurso. Como primer paso debe seleccionar la opción de Agregar ...