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

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

Resumen

Las plantillas de salida u output definen cómo será la respuesta entregada al ejecutar un método de la API. Cada plantilla se relaciona con un formato de salida (JSON, XML, CSV o RAW) y se escribe con código Jinja sobre el objeto result, con una vista previa que cambia mientras la edita. En este video ve cómo crear una plantilla nueva para el formato JSON, agregar un segundo formato y dónde quedan las plantillas de error.

Antes de comenzar

  • Abra el método en edición desde la ficha de la API. La sección Plantillas de output muestra un bloque por cada formato del método, con el selector de plantilla y los botones para crear, editar y eliminar.

Configurar plantillas

Elegir o crear la plantilla de un formato

Para definir una salida, seleccione el formato deseado y una plantilla existente en el selector Plantilla, o haga clic en el botón de crear plantilla. También puede copiar una plantilla existente para reutilizarla en su nuevo método. Las plantillas se definen mediante código de plantillas Jinja.

Bloque de plantillas de output con el selector de plantilla y los botones

Crear una plantilla

Haga clic en el botón de crear plantilla. Se abre una ventana con el editor, donde escribe el nombre de la plantilla y su código. En la misma ventana puede consultar las Referencias, que le permiten invocar los resultados de su vista de datos, y pedir ayuda al Agente de IA para generar una salida a partir de una descripción. Al confirmar con Listo, la plantilla queda seleccionada en el formato y la Vista previa del output muestra la respuesta con ella.

Agregar otro formato

En ¿Qué formato te gustaría agregar? elija CSV, JSON, RAW o XML y haga clic en Confirmar. Cada formato tiene su propia plantilla y su propia pestaña en la vista previa. Marque Formato por defecto en el que debe responder cuando la solicitud no indica formato.

Editar una plantilla

Para editar una plantilla, selecciónela y haga clic en el botón de editar. Si la plantilla está siendo utilizada por otro método se muestra un aviso: si hace clic en Editar, el cambio afecta a todos los métodos que la usan; también puede crear una copia de la plantilla solo para este método.

Borrar una plantilla

Para eliminar una plantilla, selecciónela, haga clic en el botón de eliminar y confirme la operación.

Plantillas de error

Debajo de las plantillas de output, la sección Plantillas de error define la respuesta cuando la solicitud no es exitosa, con una pestaña por cada formato del método. Vea Definir respuestas de error personalizadas.

Ayudas sobre las plantillas

Lo más fácil es tomar una plantilla de referencia, duplicarla y modificarla. Ejemplo: exponer esta vista de datos con algunas transformaciones en la salida.

Vista de datos de ejemplo con las columnas que usa la plantilla 
{
  "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 }}
}
  • Con {% for row in result.data %} se abre un bucle que recorre todas las filas de la vista para entregar los valores de cada una en un objeto dentro de un arreglo. El bucle se cierra con {% if not loop.last %},{% endif %} {% endfor %}, que agrega la coma entre objetos.
  • Con row.N se referencia la columna de cada fila: row.0 imprime la primera columna. Si la columna tiene alias, puede usarlo en lugar de la posición.
  • {{ row.0 | tojson }} imprime el valor como JSON. Requiere haber definido el formato JSON sobre esa columna en la vista.
  • {% if row.2 | length %} ... {% else %} ... {% endif %} imprime null cuando la celda está vacía.
  • {{ row.4 | float }} indica que el valor es de coma flotante y {{ row.10 | int }} que es un entero. Van sin comillas.
  • {{ result.cols }} imprime la cantidad de columnas y {{ result.timestamp }} el momento de ejecución en formato Unix Epoch.

Filtros de Jinja

  • int: convierte el valor a número entero, sin comillas. "atributo": {{ row.0 | int }}
  • float: convierte el valor a número con decimales, sin comillas. "atributo": {{ row.0 | float }}
  • replace: reemplaza valores. "atributo": "{{ row.0 | replace('created', 'creado') }}"
  • tojson y jsonify: formatean como JSON una columna definida con ese formato en la vista. "atributo": {{ row.0 | tojson }}
  • upper y lower: convierten un texto a mayúsculas o minúsculas. "atributo": "{{ row.0 | upper }}"
  • trim: elimina los espacios al comienzo y al final de un texto. "atributo": "{{ row.0 | trim }}"

Para más información sobre filtros consulte la documentación oficial de Jinja.

Operaciones de Jinja

Las plantillas permiten operaciones más complejas. En el siguiente caso, si la segunda columna de la primera fila contiene "409" se imprime una respuesta, y si no, otra. Es útil en una API de escritura donde el origen responde con código 200 pero indica en una columna que el registro ya existe.

{
  "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 %}
  }
}

Resultado esperado

El método muestra un bloque por formato con su plantilla seleccionada, y la vista previa responde con la estructura definida. Al guardar el método y publicar la versión, el gateway responde con esa plantilla según el formato pedido en la URL, por ejemplo .json o .xml.

Errores frecuentes

  • La vista previa muestra un error de plantilla: hay un error de sintaxis Jinja, por ejemplo un bucle sin cerrar o una coma de más. Revise la plantilla en el editor.
  • Un número sale entre comillas: falta el filtro int o float, o la referencia está entre comillas.

Artículos relacionados