PARÁMETROS DE CONSULTA Y VALIDACIONES DE CADENAS
FastAPI le permite declarar información adicional y validación para sus
parámetros.
Tomemos esta aplicación como ejemplo:
El parámetro de consulta q es de tipo str | None, lo que significa que es
de tipo str pero también podría ser None, y, de hecho, el valor
predeterminado es None, por lo que FastAPI sabrá que no es necesario.
VALIDACIÓN ADICIONAL
Vamos a hacer cumplir que, aunque q sea opcional, siempre que se
proporcione, su longitud no exceda los 50 caracteres.
Importar Query y Annotated
Para lograrlo, primero importe:
Query de fastapi
Annotated de typing
Úselo Annotated en el tipo para el q parámetro
¿Recuerdas que te dije antes que Annotated se puede usar para
agregar metadatos a tus parámetros en la Introducción a los tipos de
Python?
Ahora es el momento de usarlo con FastAPI.
Teníamos este tipo de anotación:
Lo que haremos es envolverlo con Annotated, por lo que se convierte
en:
Ambas versiones significan lo mismo, q es un parámetro que puede ser
un str o None, y por defecto es None.
Ahora pasemos a la parte divertida.
Añadir al parámetro Query Annotated q
Ahora que tenemos este Annotated lugar donde podemos poner más
información (en este caso alguna validación adicional),
agregamos Query dentro de Annotated y establecemos el
parámetro max_length en 50:
Tenga en cuenta que el valor predeterminado sigue siendo None, por lo
que el parámetro sigue siendo opcional.
Pero ahora, teniendo Query(max_length=50) dentro de Annotated, le
estamos diciendo a FastAPI que queremos que tenga una validación
adicional para este valor, queremos que tenga un máximo de 50
caracteres.
FastAPI ahora:
Validar los datos asegurándose de que la longitud máxima sea de
50 caracteres
Mostrar un error claro para el cliente cuando los datos no son
válidos
Documente el parámetro en la operación de ruta del esquema
OpenAPI (para que aparezca en la interfaz de usuario de
documentos automáticos)
Alternativa (antigua): Query como valor predeterminado
Las versiones anteriores de FastAPI (antes de 0.95.0) requerían que
usaras Query como valor predeterminado de tu parámetro, en lugar de
ponerlo en Annotated, hay muchas posibilidades de que veas código
usándolo, así que te lo explicaré.
Así es como lo usarías Query() como valor predeterminado del
parámetro de tu función, estableciendo el parámetro max_length en
50:
Como en este caso (sin usar Annotated) tenemos que reemplazar el
valor predeterminado None en la función con Query(), ahora
necesitamos establecer el valor predeterminado con el
parámetro Query(default=None), sirve para el mismo propósito de
definir ese valor predeterminado (al menos para FastAPI).
Query como valor predeterminado o en Annotated
Tenga en cuenta que al utilizar Query dentro de Annotated no puede
utilizar el default parámetro for Query.
En su lugar, utilice el valor predeterminado del parámetro de la función.
De lo contrario, sería incoherente.
Ventajas de Annotated
Annotated Se recomienda usar en lugar del valor predeterminado en
los parámetros de la función, es mejor por varias razones.
El valor predeterminado del parámetro de función es el
valor predeterminado real, lo cual es más intuitivo con Python en
general.
Podrías llamar a esa misma función en otros lugares sin FastAPI y
funcionaría correctamente. Si hay un parámetro obligatorio (sin valor
predeterminado), tu editor te lo notificará con un error. Python también
se quejará si lo ejecutas sin pasar el parámetro obligatorio.
Si no usas el estilo de valor predeterminado (antiguo) Annotated,
y en su lugar lo usas, si llamas a esa función sin FastAPI en otros
lugares, debes recordar pasarle los argumentos para que funcione
correctamente; de lo contrario, los valores serán diferentes a los
esperados (por ejemplo, o algo similar en lugar de [nombre faltante]). Tu
editor no se quejará al ejecutar esa función, y Python tampoco se
quejará al ejecutarla, solo cuando las operaciones internas generen un
error. QueryInfo str
Dado que Annotated puede tener más de una anotación de metadatos,
ahora puede incluso usar la misma función con otras herramientas,
como Mecanógrafo
AÑADIR MÁS VALIDACIONES
También puedes agregar un parámetro min_length:
Agregar expresiones regulares
Puede definir una expresión regular pattern con la que el parámetro
debe coincidir:
Este patrón de expresión regular específico verifica que el valor del
parámetro recibido:
^: comienza con los siguientes caracteres, no tiene caracteres
anteriores.
Fixedquery: tiene el valor exacto fixedquery.
$: termina ahí, no tiene más caracteres después de fixedquery.
Si te sientes perdido con todas estas ideas sobre expresiones
regulares, no te preocupes. Es un tema complejo para mucha gente.
Aún puedes hacer muchas cosas sin necesidad de usar expresiones
regulares.
Ahora ya sabes que siempre que los necesites podrás utilizarlos
en FastAPI.
Pydantic v1 regex en lugar de pattern
Antes de la versión 2 de Pydantic y antes de FastAPI 0.100.0, se
llamaba al parámetro regex en lugar de pattern, pero ahora está
obsoleto.
Aún puedes ver algo de código usándolo:
ero ten en cuenta que esto está obsoleto y debería actualizarse para
usar el nuevo parámetro pattern.
Valores predeterminados
Por supuesto, puedes utilizar valores predeterminados distintos de None.
Digamos que desea declarar que el q parámetro de consulta tenga
un min_length valor de 3 y un valor predeterminado de "fixedquery":
Parámetros requeridos
Cuando no necesitamos declarar más validaciones o metadatos,
podemos hacer que el q parámetro de consulta sea obligatorio
simplemente al no declarar un valor predeterminado, como:
Entonces, cuando necesitas declarar un valor como requerido mientras
usas Query, simplemente puedes no declarar un valor predeterminado:
Obligatorio, puede ser None
Puedes declarar que un parámetro acepta None, pero que sigue siendo
obligatorio. Esto obligaría a los clientes a enviar un valor, incluso si este
es None.
Para hacer eso, puede declarar que None es un tipo válido, pero
simplemente no declare un valor predeterminado:
LISTA DE PARÁMETROS DE CONSULTA / VALORES MÚLTIPLES
Cuando defines un parámetro de consulta explícitamente, Query
también puedes declararlo para recibir una lista de valores, o, dicho de
otra forma, para recibir múltiples valores.
Por ejemplo, para declarar un parámetro de consulta q que pueda
aparecer varias veces en la URL, puede escribir:
Luego, con una URL como:
Recibirías los valores de los múltiples parámetros de consulta q (foo y
bar) en una lista de Python dentro de tu función de operación de ruta,
en el parámetro de función q.
Entonces, la respuesta a esa URL sería:
Los documentos de la API interactiva se actualizarán en consecuencia
para permitir múltiples valores:
Lista de parámetros de consulta / valores múltiples con valores
predeterminados
También puede definir un list valor predeterminado si no se proporciona
ninguno:
Si vas a:
Usando solo list
También puedes utilizar list directamente en lugar de list[str]:
Declarar más metadatos
Puede agregar más información sobre el parámetro.
Esa información se incluirá en la OpenAPI generada y será utilizada por
las interfaces de usuario de la documentación y las herramientas
externas.
Puedes agregar un title:
Y un description:
Parámetros de alias
Imagina que quieres que el parámetro sea item-query.
Pero item-query no es un nombre de variable de Python válido.
Lo más cercano sería item_query. Pero aun así es necesario que sea
exactamente item-query...
Luego puedes declarar un alias, y ese alias es lo que se utilizará para
encontrar el valor del parámetro:
Parámetros en desuso
Ahora digamos que ya no te gusta este parámetro.
Debes dejarlo allí por un tiempo porque hay clientes que lo usan, pero
quieres que los documentos lo muestren claramente como obsoleto.
Luego pasa el parámetro deprecated=True a Query:
Los documentos lo mostrarán así:
Excluir parámetros de OpenAPI
Para excluir un parámetro de consulta del esquema OpenAPI generado
(y, por lo tanto, de los sistemas de documentación automática),
establezca el parámetro include_in_schemade Query en False:
Validación personalizada
Podría haber casos en los que necesite realizar alguna validación
personalizada que no se pueda realizar con los parámetros que se
muestran arriba.
En esos casos, puede utilizar una función de validación
personalizada que se aplique después de la validación normal (por
ejemplo, después de validar que el valor es a str).
Puedes lograrlo usando Pydantic's AfterValidator Dentro
de Annotated.
Por ejemplo, este validador personalizado verifica que el ID del artículo
comience con isbn-para un número de libro ISBN o con imdb- para un
ID de URL de película IMDB:
Entiende ese Código
Lo importante es usar AfterValidator una función dentro de
[nombre del archivo] Annotated.
Pero si tienes curiosidad sobre este ejemplo de código específico y aun
así te entretiene, aquí hay algunos detalles adicionales.
Cuerda con value.startswith()
¿Te diste cuenta? Una cadena que usa value.startswith() puede tomar
una tupla y verificará cada valor en la tupla:
Un artículo al azar
Con data.items() obtenemos un objeto iterable con tuplas que contienen
la clave y el valor de cada elemento del diccionario.
Convertimos este objeto iterable en uno propio list con list(data.items()).
Luego, con random.choice() podemos obtener un valor aleatorio de la
lista, por lo que obtenemos una tupla con (id, name). Será algo así
como ("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy").
Luego asignamos esos dos valores de la tupla a las variables id
y name.
Por lo tanto, si el usuario no proporcionó un ID de artículo, igualmente
recibirá una sugerencia aleatoria.
...hacemos todo esto en una sola línea simple. ¿No te encanta Python?
RESUMEN
Puede declarar validaciones y metadatos adicionales para sus
parámetros.
Validaciones genéricas y metadatos:
alias
title
description
deprecated
Validaciones específicas para cadenas:
min_length
max_length
pattern
Validaciones personalizadas utilizando AfterValidator.
En estos ejemplos viste cómo declarar validaciones para str valores.
