Класс APIKeyQuery

Класс APIKeyQuery применяется для организации аутентификации по API-ключу, который передаётся в строке запроса (query-параметре). Он наследуется от класса APIKeyBase и при вызове как зависимость возвращает значение ключа или выбрасывает ошибку HTTPException, если ключ не передан. Первым параметром передаётся имя query-параметра, в котором ожидается ключ. Вторым необязательным параметром идёт имя схемы безопасности, отображаемое в документации. Третьим параметром задаётся флаг auto_error, управляющий автоматическим выбрасыванием ошибки.

Синтаксис

from fastapi.security import APIKeyQuery

APIKeyQuery(name, scheme_name=None, auto_error=True)

Пример

Давайте создадим зависимость на основе APIKeyQuery и защитим ей маршрут:

from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import APIKeyQuery

app = FastAPI()

api_key_query = APIKeyQuery(name='api_key')

VALID_KEY = 'abcde'

@app.get('/secure')
def secure_route(api_key: str = Depends(api_key_query)):
	if api_key != VALID_KEY:
		raise HTTPException(status_code=403, detail='Forbidden')
	return {'status': 'ok'}

Результат выполнения кода для адреса /secure?api_key=abcde:

{"status": "ok"}

Пример

Если ключ не передан или передан неверно, вернётся ошибка. Проверим обращение без параметра:

curl "http://127.0.0.1:8000/secure"

Результат выполнения запроса:

{"detail": "Not authenticated"}

Пример

Давайте отключим автоматическую ошибку с помощью параметра auto_error и обработаем отсутствие ключа вручную:

from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import APIKeyQuery

app = FastAPI()

api_key_query = APIKeyQuery(name='token', auto_error=False)

VALID_KEY = 'article'

@app.get('/data')
def data_route(token: str = Depends(api_key_query)):
	if token is None:
		raise HTTPException(status_code=401, detail='Key required')
	if token != VALID_KEY:
		raise HTTPException(status_code=403, detail='Invalid key')
	return {'token': token}

Результат выполнения кода для адреса /data?token=article:

{"token": "article"}

Смотрите также

класс APIKeyHeader,
который извлекает API-ключ из заголовка запроса
класс APIKeyCookie,
который извлекает API-ключ из cookie
функция Depends,
которая внедряет зависимость в обработчик маршрута
функция Security,
которая подключает схему безопасности с областями доступа