From b6ebb11d6f154ea5d09904ccfcf38869caabb2fe Mon Sep 17 00:00:00 2001 From: Shinsuke Sugaya Date: Sun, 25 Oct 2026 01:20:57 +0900 Subject: [PATCH 1/2] docs(15.10): correct the login rate limit, log file API and status code descriptions of the API pages Update the 15.10 development tree in all seven languages. - api-auth: the login form (POST /login/login) shares the rate-limit buckets and the lockout with POST /api/v2/auth/login; a successful login clears the failures of that address and user pair but only gives back the one address slot it consumed; behind a proxy that is not listed in rate.limit.trusted.proxies all clients share one address. - api-admin-log: an unknown or disallowed log file name, or an id that is not Base64, answers a validation error (HTTP 400, status 1) instead of an empty response; ids are URL-safe Base64. - api-admin-storage: GET /api/admin/storage/list answers HTTP 400 when no storage client plugin is installed. - api-admin-dict: output of a mapping entry is required. - upgrade: add the log file, mapping output, storage listing and login form rows to the table of requests the API now refuses, and list the changes to the webauth/fileauth password, the user code of a logged-in user, "delete all" roles, role values without a cipher, unknown request charsets and dictionary failure messages. - user API pages: add the 400, 403 and 503 status codes that openapi-user.yaml declares and the tables lacked (the chat page is not changed). --- de/15.10/api/admin/api-admin-dict.rst | 2 +- de/15.10/api/admin/api-admin-log.rst | 8 +++++++- de/15.10/api/admin/api-admin-storage.rst | 4 ++-- de/15.10/api/api-auth.rst | 20 +++++++++++++++++--- de/15.10/api/api-cache.rst | 2 ++ de/15.10/api/api-click.rst | 2 ++ de/15.10/api/api-export.rst | 2 ++ de/15.10/api/api-health.rst | 2 ++ de/15.10/api/api-label.rst | 2 ++ de/15.10/api/api-related.rst | 4 ++++ de/15.10/api/api-search-history.rst | 2 ++ de/15.10/api/api-search.rst | 2 ++ de/15.10/api/api-suggest.rst | 2 ++ de/15.10/api/api-tag.rst | 2 ++ de/15.10/api/api-uiconfig.rst | 2 ++ de/15.10/install/upgrade.rst | 21 +++++++++++++++++++++ en/15.10/api/admin/api-admin-dict.rst | 2 +- en/15.10/api/admin/api-admin-log.rst | 8 +++++++- en/15.10/api/admin/api-admin-storage.rst | 4 ++-- en/15.10/api/api-auth.rst | 20 +++++++++++++++++--- en/15.10/api/api-cache.rst | 2 ++ en/15.10/api/api-click.rst | 2 ++ en/15.10/api/api-export.rst | 2 ++ en/15.10/api/api-health.rst | 2 ++ en/15.10/api/api-label.rst | 2 ++ en/15.10/api/api-related.rst | 4 ++++ en/15.10/api/api-search-history.rst | 2 ++ en/15.10/api/api-search.rst | 2 ++ en/15.10/api/api-suggest.rst | 2 ++ en/15.10/api/api-tag.rst | 2 ++ en/15.10/api/api-uiconfig.rst | 2 ++ en/15.10/install/upgrade.rst | 21 +++++++++++++++++++++ es/15.10/api/admin/api-admin-dict.rst | 2 +- es/15.10/api/admin/api-admin-log.rst | 8 +++++++- es/15.10/api/admin/api-admin-storage.rst | 4 ++-- es/15.10/api/api-auth.rst | 20 +++++++++++++++++--- es/15.10/api/api-cache.rst | 2 ++ es/15.10/api/api-click.rst | 2 ++ es/15.10/api/api-export.rst | 2 ++ es/15.10/api/api-health.rst | 2 ++ es/15.10/api/api-label.rst | 2 ++ es/15.10/api/api-related.rst | 4 ++++ es/15.10/api/api-search-history.rst | 2 ++ es/15.10/api/api-search.rst | 2 ++ es/15.10/api/api-suggest.rst | 2 ++ es/15.10/api/api-tag.rst | 2 ++ es/15.10/api/api-uiconfig.rst | 2 ++ es/15.10/install/upgrade.rst | 21 +++++++++++++++++++++ fr/15.10/api/admin/api-admin-dict.rst | 2 +- fr/15.10/api/admin/api-admin-log.rst | 8 +++++++- fr/15.10/api/admin/api-admin-storage.rst | 4 ++-- fr/15.10/api/api-auth.rst | 20 +++++++++++++++++--- fr/15.10/api/api-cache.rst | 2 ++ fr/15.10/api/api-click.rst | 2 ++ fr/15.10/api/api-export.rst | 2 ++ fr/15.10/api/api-health.rst | 2 ++ fr/15.10/api/api-label.rst | 2 ++ fr/15.10/api/api-related.rst | 4 ++++ fr/15.10/api/api-search-history.rst | 2 ++ fr/15.10/api/api-search.rst | 2 ++ fr/15.10/api/api-suggest.rst | 2 ++ fr/15.10/api/api-tag.rst | 2 ++ fr/15.10/api/api-uiconfig.rst | 2 ++ fr/15.10/install/upgrade.rst | 21 +++++++++++++++++++++ ja/15.10/api/admin/api-admin-dict.rst | 2 +- ja/15.10/api/admin/api-admin-log.rst | 8 +++++++- ja/15.10/api/admin/api-admin-storage.rst | 4 ++-- ja/15.10/api/api-auth.rst | 20 +++++++++++++++++--- ja/15.10/api/api-cache.rst | 2 ++ ja/15.10/api/api-click.rst | 2 ++ ja/15.10/api/api-export.rst | 2 ++ ja/15.10/api/api-health.rst | 2 ++ ja/15.10/api/api-label.rst | 2 ++ ja/15.10/api/api-related.rst | 4 ++++ ja/15.10/api/api-search-history.rst | 2 ++ ja/15.10/api/api-search.rst | 2 ++ ja/15.10/api/api-suggest.rst | 2 ++ ja/15.10/api/api-tag.rst | 2 ++ ja/15.10/api/api-uiconfig.rst | 2 ++ ja/15.10/install/upgrade.rst | 21 +++++++++++++++++++++ ko/15.10/api/admin/api-admin-dict.rst | 2 +- ko/15.10/api/admin/api-admin-log.rst | 8 +++++++- ko/15.10/api/admin/api-admin-storage.rst | 4 ++-- ko/15.10/api/api-auth.rst | 20 +++++++++++++++++--- ko/15.10/api/api-cache.rst | 2 ++ ko/15.10/api/api-click.rst | 2 ++ ko/15.10/api/api-export.rst | 2 ++ ko/15.10/api/api-health.rst | 2 ++ ko/15.10/api/api-label.rst | 2 ++ ko/15.10/api/api-related.rst | 4 ++++ ko/15.10/api/api-search-history.rst | 2 ++ ko/15.10/api/api-search.rst | 2 ++ ko/15.10/api/api-suggest.rst | 2 ++ ko/15.10/api/api-tag.rst | 2 ++ ko/15.10/api/api-uiconfig.rst | 2 ++ ko/15.10/install/upgrade.rst | 21 +++++++++++++++++++++ zh-cn/15.10/api/admin/api-admin-dict.rst | 2 +- zh-cn/15.10/api/admin/api-admin-log.rst | 8 +++++++- zh-cn/15.10/api/admin/api-admin-storage.rst | 4 ++-- zh-cn/15.10/api/api-auth.rst | 20 +++++++++++++++++--- zh-cn/15.10/api/api-cache.rst | 2 ++ zh-cn/15.10/api/api-click.rst | 2 ++ zh-cn/15.10/api/api-export.rst | 2 ++ zh-cn/15.10/api/api-health.rst | 2 ++ zh-cn/15.10/api/api-label.rst | 2 ++ zh-cn/15.10/api/api-related.rst | 4 ++++ zh-cn/15.10/api/api-search-history.rst | 2 ++ zh-cn/15.10/api/api-search.rst | 2 ++ zh-cn/15.10/api/api-suggest.rst | 2 ++ zh-cn/15.10/api/api-tag.rst | 2 ++ zh-cn/15.10/api/api-uiconfig.rst | 2 ++ zh-cn/15.10/install/upgrade.rst | 21 +++++++++++++++++++++ 112 files changed, 504 insertions(+), 49 deletions(-) diff --git a/de/15.10/api/admin/api-admin-dict.rst b/de/15.10/api/admin/api-admin-dict.rst index 2d950cef5..ccf4a43eb 100644 --- a/de/15.10/api/admin/api-admin-dict.rst +++ b/de/15.10/api/admin/api-admin-dict.rst @@ -422,7 +422,7 @@ Die Felder im Request-Body zum Erstellen/Aktualisieren von Wörterbucheinträgen - ``token`` (erforderlich), ``segmentation`` (erforderlich), ``reading`` (erforderlich), ``pos`` (erforderlich) - ``kuromojiFile`` * - ``mapping`` - - ``inputs`` (erforderlich), ``output`` + - ``inputs`` (erforderlich), ``output`` (erforderlich) - ``charMappingFile`` * - ``protwords`` - ``input`` (erforderlich) diff --git a/de/15.10/api/admin/api-admin-log.rst b/de/15.10/api/admin/api-admin-log.rst index 35f53fa07..b20c1baad 100644 --- a/de/15.10/api/admin/api-admin-log.rst +++ b/de/15.10/api/admin/api-admin-log.rst @@ -110,7 +110,11 @@ Lädt den Inhalt der angegebenen Protokolldatei herunter. Für ``{id}`` wird die beim Auflisten erhaltene ``id`` (der mit Base64-URL-Kodierung codierte Dateiname) unverändert angegeben. Die Antwort wird als Stream vom Typ ``application/octet-stream`` zurückgegeben. Aus Sicherheitsgründen werden nur Namen akzeptiert, die auf ``.log`` oder ``.log.gz`` enden; Namen mit Pfadmanipulationssequenzen wie ``..`` werden abgelehnt. -Wird ein nicht existierender Dateiname oder ein als Protokolldatei nicht zulässiger Name angegeben, wird eine leere Antwort zurückgegeben. +Wird ein nicht existierender Dateiname, ein als Protokolldatei nicht zulässiger Name oder eine ``id`` angegeben, die kein gültiges Base64 ist, wird ein Validierungsfehler zurückgegeben (HTTP ``400``, ``status`` im Antwort-Body ist ``1``). + +.. note:: + + Die ``id`` ist URL-sicheres Base64 (mit ``-`` und ``_``). Eine ``id`` im Standardalphabet (``+`` und ``/``) wird ebenfalls akzeptiert; um Mehrdeutigkeiten beim Einfügen in eine URL zu vermeiden, verwenden Sie jedoch die beim Auflisten erhaltene ``id`` unverändert. Request ------- @@ -124,6 +128,8 @@ Response Binärer Stream der Protokolldatei (``Content-Type: application/octet-stream``). +Wird keine Protokolldatei mit dem angegebenen Namen gefunden, wird eine Fehlerantwort mit HTTP ``400`` und ``status`` ``1`` im Antwort-Body zurückgegeben (keine leere Antwort). + Verwendungsbeispiele ==================== diff --git a/de/15.10/api/admin/api-admin-storage.rst b/de/15.10/api/admin/api-admin-storage.rst index 4ec377e64..61c4c9963 100644 --- a/de/15.10/api/admin/api-admin-storage.rst +++ b/de/15.10/api/admin/api-admin-storage.rst @@ -10,7 +10,7 @@ Sie können Dateien und Verzeichnisse im Speicher auflisten sowie Dateien herunt .. note:: - Diese API lässt sich nur verwenden, wenn ein Plugin installiert ist, das den Speicher-Client bereitstellt: ``fess-storage-s3`` für Amazon S3 und S3-kompatiblen Speicher oder ``fess-storage-gcs`` für Google Cloud Storage. Die Plugins sind nicht in der Distribution enthalten. Ohne eines gibt es keinen Client für den konfigurierten ``storage.type``, und die Anfragen schlagen fehl. Installieren Sie das Plugin auf der Seite „System“ > „Plugin“ der Administrationsoberfläche oder mit ``bin/fess-setup install plugin fess-storage-s3`` (für GCS ``fess-storage-gcs``). + Diese API lässt sich nur verwenden, wenn ein Plugin installiert ist, das den Speicher-Client bereitstellt: ``fess-storage-s3`` für Amazon S3 und S3-kompatiblen Speicher oder ``fess-storage-gcs`` für Google Cloud Storage. Die Plugins sind nicht in der Distribution enthalten. Ohne eines gibt es keinen Client für den konfigurierten ``storage.type``, und die Anfragen schlagen fehl. ``GET /api/admin/storage/list`` liefert zum Beispiel keine leere Liste, sondern einen Fehler mit HTTP ``400`` (``status`` ist ``1``), dessen ``message`` den Text ``No storage client is registered as ...`` (nach dem Präfix „Storage Access Error“) enthält und das zu installierende Plugin nennt. Installieren Sie das Plugin auf der Seite „System“ > „Plugin“ der Administrationsoberfläche oder mit ``bin/fess-setup install plugin fess-storage-s3`` (für GCS ``fess-storage-gcs``). Basis-URL ========= @@ -228,7 +228,7 @@ Die häufigsten Fehlerfälle sind wie folgt. * - Endpunkt - Häufige Fehlerursachen * - Dateien und Verzeichnisse auflisten - - Wenn die Anzahl der abgerufenen Einträge das Limit überschreitet + - Wenn die Anzahl der abgerufenen Einträge das Limit überschreitet oder wenn auf den Speicher nicht zugegriffen werden kann (auch wenn kein Plugin für den Speicher-Client installiert ist) * - Datei herunterladen - Wenn ``id`` ungültig ist oder der Download fehlschlägt * - Datei löschen diff --git a/de/15.10/api/api-auth.rst b/de/15.10/api/api-auth.rst index 25cc6d483..2f49752d2 100644 --- a/de/15.10/api/api-auth.rst +++ b/de/15.10/api/api-auth.rst @@ -145,6 +145,8 @@ Fehlerantwort * - Statuscode - Beschreibung + * - 400 Bad Request + - Wenn ein Anfrageparameter angegeben wurde, der sich nicht dekodieren lässt (zum Beispiel ``?q=%ff``). ``error.code`` ist ``invalid_request``. * - 405 Method Not Allowed - Wenn eine nicht unterstützte HTTP-Methode angegeben wurde. * - 500 Internal Server Error @@ -162,7 +164,7 @@ Endpunkt ``/api/v2/auth/login`` ================== ==================================================== Meldet den Benutzer mit Benutzername und Passwort an. -Bei erfolgreicher Anmeldung wird die Servlet-Sitzungs-ID rotiert, ein neues CSRF-Token ausgestellt und die Rate-Limit-Buckets der aufrufenden IP und des Zielbenutzers geleert. +Bei erfolgreicher Anmeldung wird die Servlet-Sitzungs-ID rotiert, ein neues CSRF-Token ausgestellt. Außerdem wird die Aufzeichnung früherer fehlgeschlagener Versuche für dieselbe Kombination aus aufrufender IP und Benutzername (der Bucket pro Benutzer) geleert. Der Bucket pro IP wird nicht geleert, da er auch Versuche gegen andere Benutzer von derselben IP zählt; zurückgegeben wird nur der eine Platz, den dieser Versuch belegt hat. Das Rate-Limiting erfolgt nach zwei Dimensionen: pro aufrufender IP und pro Benutzer. Bei Überschreitung des IP-seitigen Limits wird ``429 Too Many Requests`` zusammen mit einem ``Retry-After``-Header (in Sekunden) zurückgegeben. Bei Überschreitung des benutzerseitigen Limits wird – um den Zählerzustand von außen nicht erkennbar zu machen – dieselbe ``401 Unauthorized``-Antwort wie bei ungültigen Anmeldedaten zurückgegeben (ohne ``Retry-After``-Header). @@ -183,10 +185,14 @@ Außerdem werden protokollrelative Pfade (führendes ``//``) und Pfade mit ASCII Die Rate-Limits für Anmeldung und Passwortänderung können mit folgenden Eigenschaften konfiguriert werden (Standardwerte in Klammern): - - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): Maximale Anzahl von Versuchen pro Minute und IP-Adresse. Gilt nur für ``/auth/login``. - - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): Maximale Anzahl von Versuchen pro Minute und Benutzer. Gilt sowohl für ``/auth/login`` als auch für ``/auth/password``. + - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): Maximale Anzahl von Versuchen pro Minute und IP-Adresse. Gilt sowohl für ``/auth/login`` als auch für das Anmeldeformular ``POST /login/login``; beide teilen sich denselben Bucket. + - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): Maximale Anzahl von Versuchen pro Minute und Benutzer. Gilt für ``/auth/login`` und ``POST /login/login`` (diese teilen sich je Kombination aus aufrufender IP und Benutzername einen Bucket) sowie für ``/auth/password``. - ``theme.api.login.lockout.seconds`` (``900``): Sperrungsdauer (in Sekunden) nach Überschreitung des Limits. Wird als Wert des ``Retry-After``-Headers zurückgegeben. + Das Anmeldeformular (``POST /login/login``) teilt sich die Buckets und die Sperrung mit ``/auth/login``; Fehlversuche am Formular zählen daher zum Limit von ``/auth/login`` und umgekehrt. Wird das Limit am Formular überschritten, wird dies als gewöhnlicher Anmeldefehler behandelt und nicht mit ``429`` beantwortet. + + Hinter einem Reverse-Proxy, der nicht in ``rate.limit.trusted.proxies`` (Standard ``127.0.0.1,::1``) aufgeführt ist, werden alle Clients als eine einzige IP-Adresse (die des Proxys) behandelt. Wiederholte fehlgeschlagene Anmeldungen können dann für die Dauer der Sperrung alle Benutzer aussperren. Tragen Sie die Adresse des Proxys in ``rate.limit.trusted.proxies`` ein, damit die tatsächliche Client-IP aus ``X-Forwarded-For`` übernommen wird. + Anfrage-Body (LoginRequest) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -284,12 +290,16 @@ Fehlerantwort - Wenn die Anfrage ungültig ist (einschließlich übermäßig großer Request-Bodys und nicht unterstützter ``Content-Type``-Werte). * - 401 Unauthorized - Wenn die Anmeldedaten ungültig sind. + * - 403 Forbidden + - Wenn die Anfrage als Cross-Site-Anfrage blockiert wurde: Der Header ``Origin`` (oder ``Referer``) nennt einen nicht zulässigen Origin. Dies ist die grundlegende Prüfung, die jede zustandsändernde Anfrage durchläuft, und ist vom CSRF-Token getrennt, das die Anmeldung nicht benötigt. * - 405 Method Not Allowed - Wenn eine nicht unterstützte HTTP-Methode angegeben wurde. * - 429 Too Many Requests - Wenn das Rate-Limit überschritten wurde. Der ``Retry-After``-Header gibt die Wartezeit in Sekunden an. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. Abmelden ======== @@ -344,6 +354,8 @@ Fehlerantwort * - Statuscode - Beschreibung + * - 400 Bad Request + - Wenn ein Anfrageparameter angegeben wurde, der sich nicht dekodieren lässt (zum Beispiel ``?q=%ff``). ``error.code`` ist ``invalid_request``. * - 403 Forbidden - Wenn der CSRF-Token fehlt oder abgelaufen ist. * - 405 Method Not Allowed @@ -456,3 +468,5 @@ Fehlerantwort - Wenn das Rate-Limit überschritten wurde. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. diff --git a/de/15.10/api/api-cache.rst b/de/15.10/api/api-cache.rst index e5a6a72bb..dcb114f16 100644 --- a/de/15.10/api/api-cache.rst +++ b/de/15.10/api/api-cache.rst @@ -96,5 +96,7 @@ Details zum Fehlermodell finden Sie unter :doc:`api-overview`. Folgende HTTP-Sta - Wenn die HTTP-Methode nicht erlaubt ist. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. Tabelle: Fehlerantwort diff --git a/de/15.10/api/api-click.rst b/de/15.10/api/api-click.rst index 83de94f74..000ec182c 100644 --- a/de/15.10/api/api-click.rst +++ b/de/15.10/api/api-click.rst @@ -108,5 +108,7 @@ Details zum Fehlermodell finden Sie unter :doc:`api-overview`. Folgende HTTP-Sta - Der ``Content-Type`` ist nicht ``application/json`` (UTF-8 ist erforderlich). * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. Tabelle: Fehlerantwort diff --git a/de/15.10/api/api-export.rst b/de/15.10/api/api-export.rst index ef72afee2..7306157cd 100644 --- a/de/15.10/api/api-export.rst +++ b/de/15.10/api/api-export.rst @@ -94,5 +94,7 @@ Fehlerantwort - Wenn das Anfragelimit pro Minute überschritten ist. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. Tabelle: Fehlerantwort diff --git a/de/15.10/api/api-health.rst b/de/15.10/api/api-health.rst index fb4b784c7..afbe10262 100644 --- a/de/15.10/api/api-health.rst +++ b/de/15.10/api/api-health.rst @@ -104,6 +104,8 @@ Details zum Fehlermodell finden Sie unter :doc:`api-overview`. Folgende HTTP-Sta - Beschreibung * - 200 OK - Cluster ist ``GREEN`` oder ``YELLOW`` und erreichbar. Der Erfolgs-Envelope enthält ``engine``. + * - 400 Bad Request + - Wenn ein Anfrageparameter angegeben wurde, der sich nicht dekodieren lässt (zum Beispiel ``?q=%ff``). ``error.code`` ist ``invalid_request``. * - 405 Method Not Allowed - Wenn die HTTP-Methode nicht erlaubt ist. * - 503 Service Unavailable diff --git a/de/15.10/api/api-label.rst b/de/15.10/api/api-label.rst index 86c03f60c..274f42cd9 100644 --- a/de/15.10/api/api-label.rst +++ b/de/15.10/api/api-label.rst @@ -90,6 +90,8 @@ Details zum Fehlermodell finden Sie unter :doc:`api-overview`. Folgende HTTP-Sta * - Statuscode - Beschreibung + * - 400 Bad Request + - Wenn ein Anfrageparameter angegeben wurde, der sich nicht dekodieren lässt (zum Beispiel ``?q=%ff``). ``error.code`` ist ``invalid_request``. * - 401 Unauthorized - Wenn eine Authentifizierung erforderlich ist (Anmeldepflicht aktiviert und anonymer Aufrufer, oder die Anfrage enthält ein nicht registriertes oder abgelaufenes Zugriffstoken). ``error.code`` ist ``auth_required``. * - 405 Method Not Allowed diff --git a/de/15.10/api/api-related.rst b/de/15.10/api/api-related.rst index ff54bcd14..143d793d1 100644 --- a/de/15.10/api/api-related.rst +++ b/de/15.10/api/api-related.rst @@ -78,6 +78,8 @@ Fehlerantwort * - Statuscode - Beschreibung + * - 400 Bad Request + - Wenn ein Anfrageparameter angegeben wurde, der sich nicht dekodieren lässt (zum Beispiel ``?q=%ff``). ``error.code`` ist ``invalid_request``. * - 401 Unauthorized - Wenn eine Authentifizierung erforderlich ist (Anmeldepflicht-Einstellung aktiviert und anonymer Aufrufer). ``error.code`` ist ``auth_required``. * - 405 Method Not Allowed @@ -152,6 +154,8 @@ Fehlerantwort * - Statuscode - Beschreibung + * - 400 Bad Request + - Wenn ein Anfrageparameter angegeben wurde, der sich nicht dekodieren lässt (zum Beispiel ``?q=%ff``). ``error.code`` ist ``invalid_request``. * - 401 Unauthorized - Wenn eine Authentifizierung erforderlich ist (Anmeldepflicht-Einstellung aktiviert und anonymer Aufrufer). ``error.code`` ist ``auth_required``. * - 405 Method Not Allowed diff --git a/de/15.10/api/api-search-history.rst b/de/15.10/api/api-search-history.rst index 35fd31d56..7ebe5eae4 100644 --- a/de/15.10/api/api-search-history.rst +++ b/de/15.10/api/api-search-history.rst @@ -104,6 +104,8 @@ Fehlerantwort - Wenn die HTTP-Methode nicht zulässig ist. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. Tabelle: Fehlerantwort diff --git a/de/15.10/api/api-search.rst b/de/15.10/api/api-search.rst index 8c4913130..60e94e40d 100644 --- a/de/15.10/api/api-search.rst +++ b/de/15.10/api/api-search.rst @@ -291,6 +291,8 @@ Details zum Fehlermodell finden Sie unter :doc:`api-overview`. Folgende HTTP-Sta - Wenn die HTTP-Methode nicht erlaubt ist. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. Tabelle: Fehlerantwort diff --git a/de/15.10/api/api-suggest.rst b/de/15.10/api/api-suggest.rst index 5aadf656c..c0066c124 100644 --- a/de/15.10/api/api-suggest.rst +++ b/de/15.10/api/api-suggest.rst @@ -127,3 +127,5 @@ Wenn die Vorschlags-API fehlschlägt, wird der gemeinsame Fehler-Envelope zurüc - Wenn eine nicht unterstützte HTTP-Methode angegeben wurde. Der ``Allow``-Header gibt ``GET`` an. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. diff --git a/de/15.10/api/api-tag.rst b/de/15.10/api/api-tag.rst index 4e93ed781..a103052d8 100644 --- a/de/15.10/api/api-tag.rst +++ b/de/15.10/api/api-tag.rst @@ -401,6 +401,8 @@ HTTP-Status zurück. - Wenn der ``Content-Type`` nicht unterstützt wird. * - 500 Internal Server Error - Wenn ein interner Serverfehler auftritt. + * - 503 Service Unavailable + - Wenn die Suchmaschine die Anfrage nicht entgegennehmen konnte: Sie ist nicht erreichbar oder hat die Anfrage wegen fehlender Kapazität abgelehnt. ``error.code`` ist ``service_unavailable``, und ein ``Retry-After``-Header nennt die Wartezeit in Sekunden (``5``). Die Anfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut. Tabelle: Fehlerantwort diff --git a/de/15.10/api/api-uiconfig.rst b/de/15.10/api/api-uiconfig.rst index bce93dbca..7569685bd 100644 --- a/de/15.10/api/api-uiconfig.rst +++ b/de/15.10/api/api-uiconfig.rst @@ -406,6 +406,8 @@ Fehlerantwort * - Statuscode - Beschreibung + * - 400 Bad Request + - Wenn ein Anfrageparameter angegeben wurde, der sich nicht dekodieren lässt (zum Beispiel ``?q=%ff``). ``error.code`` ist ``invalid_request``. * - 405 Method Not Allowed - Wenn eine nicht unterstützte HTTP-Methode angegeben wurde. * - 500 Internal Server Error diff --git a/de/15.10/install/upgrade.rst b/de/15.10/install/upgrade.rst index 3c5ee1ce5..30546d7bb 100644 --- a/de/15.10/install/upgrade.rst +++ b/de/15.10/install/upgrade.rst @@ -1267,6 +1267,18 @@ Sie für 15.8 geschrieben haben. Die Admin-API beantwortet eine Ablehnung mit HT * - Ein Benutzer in der Admin-API, dessen Passwort die Passwortrichtlinie verletzt (etwa ``password.min.length``, Standard ``8``); eine Anlage ohne Passwort; ein ``confirm_password``, das von ``password`` abweicht - Wird gespeichert; der Benutzer kann sich mit diesem Passwort anmelden - ``400`` + * - ``GET /api/admin/log/file/{id}`` mit einem Namen, der für eine Protokolldatei nicht zulässig ist (etwa ohne die Endung ``.log`` oder ``.log.gz``), oder mit einer Datei, die nicht im Protokollverzeichnis liegt + - Nicht zulässiger Name: ``200`` mit leerer Antwort + - ``400`` + * - Ein Eintrag im Wörterbuch ``mapping`` ohne ``output``, über die Admin-API angelegt oder aktualisiert + - ``200`` (``id`` ist ``0``); es wird nichts gespeichert + - ``400`` + * - ``GET /api/admin/storage/list``, wenn auf den Speicher nicht zugegriffen werden kann, auch wenn kein Plugin für den Speicher-Client installiert ist + - ``200`` (``status`` ``0``) mit leerer Liste + - ``400``. ``message`` nennt die Ursache und, falls das Plugin fehlt, das zu installierende Plugin + * - Wiederholte fehlgeschlagene Anmeldungen am Anmeldeformular (``POST /login/login``) innerhalb kurzer Zeit von einer IP-Adresse oder für einen Benutzer von einer IP-Adresse + - Keine Begrenzung + - Oberhalb des Limits pro Adresse oder pro Benutzer (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``) werden weitere Anmeldungen von dieser Adresse (beim Limit pro Benutzer: für diesen Benutzer von dieser Adresse) ``theme.api.login.lockout.seconds`` Sekunden lang abgelehnt, auch mit korrekten Anmeldedaten. Die Antwort ist dieselbe Anmeldefehlermeldung wie bei falschen Anmeldedaten. Limits und Sperrung werden mit ``/api/v2/auth/login`` geteilt (siehe :doc:`../api/api-auth`) Die Zeilen von ``/api/v2/documents/all`` enthalten kein ``score`` mehr. Bis 15.8 hatte jedes Dokument seinen Suchscore; 15.10 durchläuft das gesamte Ergebnis mit einem Point in Time und ``search_after``, wodurch kein @@ -1279,6 +1291,15 @@ per ``POST`` entgegengenommen. Die Dokumentation von 15.8 empfahl ``PUT``, doch fehlschlägt, dass die Datei erforderlich ist. Die ``PUT``-Endpunkte bleiben bestehen; verwenden Sie für Uploads ``POST``. +Die folgenden Änderungen sind keine Ablehnungen, können aber Skripte und Clients der API und der Administrationsoberfläche betreffen. + +- Die ``GET``-Anfragen der Admin-APIs ``webauth`` und ``fileauth`` (``/api/admin/webauth/settings``, ``/api/admin/webauth/setting/{id}`` und dieselben Endpunkte unter ``fileauth``) liefern das gespeicherte Passwort nicht mehr zurück. Ein ``PUT`` ohne Passwort oder mit leerem Passwort behält das gespeicherte Passwort; ein nicht leeres Passwort ersetzt es. +- Ein angemeldeter Benutzer wird anhand der Sitzung erkannt, nicht anhand eines ``userCode``-Parameters oder -Cookies, den die Anfrage mitbringt (zum Beispiel bei der Favoriten-API). Anonyme Benutzer verwenden weiterhin den Parameter und das Cookie. +- „Alle löschen“ in den Bildschirmen „Suchliste“ und „Crawl-Informationen“ der Administrationsoberfläche erfordert die Bearbeitungsrolle (``admin-searchlist``, ``admin-crawlinginfo``). Die Anfrage eines Benutzers, der nur die Leserolle besitzt (die Rolle mit dem Suffix ``-view``), wird abgelehnt. +- Haben Sie in der Komponente ``roleQueryHelper`` der Datei ``fess.xml`` ``parameterKey``, ``headerKey`` oder ``cookieKey`` aktiviert, aber keinen ``cipher`` gesetzt, und steht das Verschlüsselungs-Flag (``encryptedParameterValue``, ``encryptedHeaderValue`` oder ``encryptedCookieValue``) noch auf dem Standardwert ``true``, hat 15.8 den Wert als unverschlüsselte Rolleninformation gelesen. 15.10 ignoriert den Wert und schreibt einmalig eine Warnung ins Log. Setzen Sie einen ``cipher``, wenn die Werte verschlüsselt sind, oder setzen Sie das Flag auf ``false``, wenn sie unverschlüsselt eintreffen sollen. +- Eine Anfrage, deren ``Content-Type`` einen der JVM unbekannten Zeichensatz nennt (zum Beispiel ``charset=nope``), wird wie eine Anfrage ohne Zeichensatz behandelt. ``/api/v2/search`` antwortete darauf bisher mit ``500`` (``internal_error``). +- Schlägt ein Upload oder Download über die Admin-API für das Wörterbuch ``kuromoji``, ``mapping``, ``stemmeroverride`` oder ``synonym`` fehl, nennt die Meldung jetzt dieses Wörterbuch. In 15.8 stand bei allen „protwords file“. + ``search_engine.type=cloud`` ist veraltet ----------------------------------------- diff --git a/en/15.10/api/admin/api-admin-dict.rst b/en/15.10/api/admin/api-admin-dict.rst index 90223208b..3ef92979e 100644 --- a/en/15.10/api/admin/api-admin-dict.rst +++ b/en/15.10/api/admin/api-admin-dict.rst @@ -422,7 +422,7 @@ The fields of the request body and response for creating and updating dictionary - ``token`` (required), ``segmentation`` (required), ``reading`` (required), ``pos`` (required) - ``kuromojiFile`` * - ``mapping`` - - ``inputs`` (required), ``output`` + - ``inputs`` (required), ``output`` (required) - ``charMappingFile`` * - ``protwords`` - ``input`` (required) diff --git a/en/15.10/api/admin/api-admin-log.rst b/en/15.10/api/admin/api-admin-log.rst index 31842c0fc..3db267602 100644 --- a/en/15.10/api/admin/api-admin-log.rst +++ b/en/15.10/api/admin/api-admin-log.rst @@ -110,7 +110,11 @@ Downloads the contents of the specified log file. For ``{id}``, specify the ``id`` (the file name encoded with Base64 URL encoding) returned by the file list retrieval as-is. The response is returned as an ``application/octet-stream`` stream. For security, only names ending with ``.log`` or ``.log.gz`` are accepted, and names containing path manipulation sequences such as ``..`` are rejected. -If you specify a non-existent file name or a name that is not permitted as a log file, an empty response is returned. +If you specify a non-existent file name, a name that is not permitted as a log file, or an ``id`` that is not valid Base64, a validation error is returned (HTTP ``400``, with ``status`` set to ``1`` in the response body). + +.. note:: + + The ``id`` is URL-safe Base64 (using ``-`` and ``_``). An ``id`` in the standard alphabet (``+`` and ``/``) is also accepted, but to avoid ambiguity when it is placed in a URL, use the ``id`` returned by the file list retrieval as-is. Request ------- @@ -124,6 +128,8 @@ Response A binary stream of the log file (``Content-Type: application/octet-stream``). +If no log file with the specified name is found, an error response with HTTP ``400`` and ``status`` set to ``1`` in the response body is returned (not an empty response). + Usage Examples ============== diff --git a/en/15.10/api/admin/api-admin-storage.rst b/en/15.10/api/admin/api-admin-storage.rst index aaf8b97de..e23b67324 100644 --- a/en/15.10/api/admin/api-admin-storage.rst +++ b/en/15.10/api/admin/api-admin-storage.rst @@ -10,7 +10,7 @@ You can list files and directories in storage, and download, delete, and upload .. note:: - This API can be used only when a plugin that provides the storage client is installed: ``fess-storage-s3`` for Amazon S3 and S3-compatible storage, or ``fess-storage-gcs`` for Google Cloud Storage. The plugins are not bundled with the distribution. Without one, there is no client for the configured ``storage.type`` and the requests fail. Install the plugin on the "System" > "Plugin" page of the admin UI or with ``bin/fess-setup install plugin fess-storage-s3`` (``fess-storage-gcs`` for GCS). + This API can be used only when a plugin that provides the storage client is installed: ``fess-storage-s3`` for Amazon S3 and S3-compatible storage, or ``fess-storage-gcs`` for Google Cloud Storage. The plugins are not bundled with the distribution. Without one, there is no client for the configured ``storage.type`` and the requests fail. For example, ``GET /api/admin/storage/list`` does not return an empty list but an error with HTTP ``400`` (``status`` is ``1``), whose ``message`` contains ``No storage client is registered as ...`` (after the "Storage Access Error" prefix) and names the plugin to install. Install the plugin on the "System" > "Plugin" page of the admin UI or with ``bin/fess-setup install plugin fess-storage-s3`` (``fess-storage-gcs`` for GCS). Base URL ======== @@ -228,7 +228,7 @@ The main error cases are as follows. * - Endpoint - Main cases where an error occurs * - List Files and Directories - - When the number of retrieved items exceeds the limit + - When the number of retrieved items exceeds the limit, or when the storage cannot be accessed (including when no storage client plugin is installed) * - Download a File - When ``id`` is invalid, or when the download fails * - Delete a File diff --git a/en/15.10/api/api-auth.rst b/en/15.10/api/api-auth.rst index 57ea900e8..f118867eb 100644 --- a/en/15.10/api/api-auth.rst +++ b/en/15.10/api/api-auth.rst @@ -145,6 +145,8 @@ Error Response * - Status Code - Description + * - 400 Bad Request + - A request parameter that cannot be decoded (for example ``?q=%ff``) was given. ``error.code`` is ``invalid_request``. * - 405 Method Not Allowed - An unsupported HTTP method was specified. * - 500 Internal Server Error @@ -162,7 +164,7 @@ Endpoint ``/api/v2/auth/login`` ================== ==================================================== Logs in with a username and password. -On successful login, the servlet session ID is rotated, a new CSRF token is issued, and the rate-limit buckets for the caller's IP and the target user are cleared. +On successful login, the servlet session ID is rotated, and a new CSRF token is issued. In addition, the record of earlier failed attempts for the same caller IP and username (the per-user bucket) is cleared. The per-IP bucket is not cleared, because it also counts attempts made at other users from the same IP; only the one slot consumed by this attempt is given back. Rate limiting is applied along two axes: per caller IP and per user. When the per-IP limit is exceeded, ``429 Too Many Requests`` is returned together with a ``Retry-After`` header (in seconds). When the per-user limit is exceeded, the same ``401 Unauthorized`` as for invalid credentials is returned (without a ``Retry-After`` header), so that the state of the counter cannot be inferred from outside. @@ -183,10 +185,14 @@ Additionally, protocol-relative paths (starting with ``//``) and paths containin The rate limits for login and password change can be configured with the following properties (defaults in parentheses): - - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): Maximum number of attempts per minute per IP address. Applies only to ``/auth/login``. - - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): Maximum number of attempts per minute per user. Applies to both ``/auth/login`` and ``/auth/password``. + - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): Maximum number of attempts per minute per IP address. Applies to both ``/auth/login`` and the login form ``POST /login/login``, which share the same bucket. + - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): Maximum number of attempts per minute per user. Applies to ``/auth/login`` and ``POST /login/login`` (which share one bucket for each pair of caller IP and username) and to ``/auth/password``. - ``theme.api.login.lockout.seconds`` (``900``): Lockout duration (in seconds) after the limit is exceeded. Returned as the value of the ``Retry-After`` header. + The login form (``POST /login/login``) shares the buckets and the lockout with ``/auth/login``, so failures on the form count toward the ``/auth/login`` limit and vice versa. When the limit is exceeded on the form, it is handled as an ordinary login error instead of ``429``. + + Behind a reverse proxy that is not listed in ``rate.limit.trusted.proxies`` (default ``127.0.0.1,::1``), all clients are treated as one IP address (the proxy's address). Repeated failed logins can then lock out every user for the duration of the lockout. Add the proxy's address to ``rate.limit.trusted.proxies`` so that the actual client IP is taken from ``X-Forwarded-For``. + Request Body (LoginRequest) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -284,12 +290,16 @@ Error Response - The request is invalid (including oversized request body or unsupported ``Content-Type``). * - 401 Unauthorized - The credentials are invalid. + * - 403 Forbidden + - The request was blocked as cross-site: its ``Origin`` (or ``Referer``) header names an origin that is not allowed. This is the baseline check that every state-changing request passes, and is separate from the CSRF token, which login does not need. * - 405 Method Not Allowed - An unsupported HTTP method was specified. * - 429 Too Many Requests - The rate limit was exceeded. The ``Retry-After`` header indicates the number of seconds to wait. * - 500 Internal Server Error - An internal server error occurred. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. Logout ====== @@ -344,6 +354,8 @@ Error Response * - Status Code - Description + * - 400 Bad Request + - A request parameter that cannot be decoded (for example ``?q=%ff``) was given. ``error.code`` is ``invalid_request``. * - 403 Forbidden - The CSRF token is missing or expired. * - 405 Method Not Allowed @@ -456,3 +468,5 @@ Error Response - The rate limit was exceeded. * - 500 Internal Server Error - An internal server error occurred. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. diff --git a/en/15.10/api/api-cache.rst b/en/15.10/api/api-cache.rst index bba21bcc6..154636f8e 100644 --- a/en/15.10/api/api-cache.rst +++ b/en/15.10/api/api-cache.rst @@ -96,5 +96,7 @@ For details on the error model, see :doc:`api-overview`. The HTTP statuses retur - The HTTP method is not allowed. * - 500 Internal Server Error - An internal server error occurred. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. Table: Error Response diff --git a/en/15.10/api/api-click.rst b/en/15.10/api/api-click.rst index c9767ca6f..f54d8cfc5 100644 --- a/en/15.10/api/api-click.rst +++ b/en/15.10/api/api-click.rst @@ -108,5 +108,7 @@ For details on the error model, see :doc:`api-overview`. The HTTP statuses retur - The ``Content-Type`` is not ``application/json`` (UTF-8 is required). * - 500 Internal Server Error - An internal server error occurred. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. Table: Error Response diff --git a/en/15.10/api/api-export.rst b/en/15.10/api/api-export.rst index 2ae82ce42..aeca8c75f 100644 --- a/en/15.10/api/api-export.rst +++ b/en/15.10/api/api-export.rst @@ -90,5 +90,7 @@ Error Response - When the per-minute request limit is exceeded. * - 500 Internal Server Error - When an internal server error occurs. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. Table: Error Response diff --git a/en/15.10/api/api-health.rst b/en/15.10/api/api-health.rst index 6652f1eea..6d1a798f6 100644 --- a/en/15.10/api/api-health.rst +++ b/en/15.10/api/api-health.rst @@ -104,6 +104,8 @@ For details on the error model, see :doc:`api-overview`. The HTTP statuses retur - Description * - 200 OK - Cluster is ``GREEN`` or ``YELLOW`` and reachable. The success envelope contains ``engine``. + * - 400 Bad Request + - A request parameter that cannot be decoded (for example ``?q=%ff``) was given. ``error.code`` is ``invalid_request``. * - 405 Method Not Allowed - The HTTP method is not allowed. * - 503 Service Unavailable diff --git a/en/15.10/api/api-label.rst b/en/15.10/api/api-label.rst index 82d720acd..1a2f8e9da 100644 --- a/en/15.10/api/api-label.rst +++ b/en/15.10/api/api-label.rst @@ -90,6 +90,8 @@ For details on the error model, see :doc:`api-overview`. The HTTP statuses retur * - Status Code - Description + * - 400 Bad Request + - A request parameter that cannot be decoded (for example ``?q=%ff``) was given. ``error.code`` is ``invalid_request``. * - 401 Unauthorized - Authentication is required (the login-required setting is enabled with an anonymous caller, or the request carries an access token that is not registered or has expired). ``error.code`` is ``auth_required``. * - 405 Method Not Allowed diff --git a/en/15.10/api/api-related.rst b/en/15.10/api/api-related.rst index b3315de26..a28f62bdc 100644 --- a/en/15.10/api/api-related.rst +++ b/en/15.10/api/api-related.rst @@ -78,6 +78,8 @@ Error Response * - Status Code - Description + * - 400 Bad Request + - A request parameter that cannot be decoded (for example ``?q=%ff``) was given. ``error.code`` is ``invalid_request``. * - 401 Unauthorized - Authentication is required (the login-required setting is enabled with an anonymous caller). ``error.code`` is ``auth_required``. * - 405 Method Not Allowed @@ -152,6 +154,8 @@ Error Response * - Status Code - Description + * - 400 Bad Request + - A request parameter that cannot be decoded (for example ``?q=%ff``) was given. ``error.code`` is ``invalid_request``. * - 401 Unauthorized - Authentication is required (the login-required setting is enabled with an anonymous caller). ``error.code`` is ``auth_required``. * - 405 Method Not Allowed diff --git a/en/15.10/api/api-search-history.rst b/en/15.10/api/api-search-history.rst index 893a85fd3..818c86a64 100644 --- a/en/15.10/api/api-search-history.rst +++ b/en/15.10/api/api-search-history.rst @@ -101,6 +101,8 @@ Error Response - When the HTTP method is not allowed. * - 500 Internal Server Error - When an internal server error occurs. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. Table: Error Response diff --git a/en/15.10/api/api-search.rst b/en/15.10/api/api-search.rst index 4886146b8..667ecc842 100644 --- a/en/15.10/api/api-search.rst +++ b/en/15.10/api/api-search.rst @@ -291,6 +291,8 @@ For details on the error model, see :doc:`api-overview`. The HTTP statuses retur - The HTTP method is not allowed. * - 500 Internal Server Error - An internal server error occurred. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. Table: Error Response diff --git a/en/15.10/api/api-suggest.rst b/en/15.10/api/api-suggest.rst index cad20a234..8b4a7c1e3 100644 --- a/en/15.10/api/api-suggest.rst +++ b/en/15.10/api/api-suggest.rst @@ -127,3 +127,5 @@ When the Suggest API fails, a common error envelope is returned. For details on - An unsupported HTTP method was specified. The ``Allow`` header indicates ``GET``. * - 500 Internal Server Error - An internal server error occurred. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. diff --git a/en/15.10/api/api-tag.rst b/en/15.10/api/api-tag.rst index 62296a013..32a9ba4bc 100644 --- a/en/15.10/api/api-tag.rst +++ b/en/15.10/api/api-tag.rst @@ -383,6 +383,8 @@ HTTP statuses. - When the ``Content-Type`` is not supported. * - 500 Internal Server Error - When an internal server error occurs. + * - 503 Service Unavailable + - The search engine could not take the request: it is not reachable, or it refused the request for lack of capacity. ``error.code`` is ``service_unavailable``, and a ``Retry-After`` header gives the number of seconds to wait (``5``). The request itself is fine, so retry after a short wait. Table: Error Response diff --git a/en/15.10/api/api-uiconfig.rst b/en/15.10/api/api-uiconfig.rst index 99987657f..83a0b56db 100644 --- a/en/15.10/api/api-uiconfig.rst +++ b/en/15.10/api/api-uiconfig.rst @@ -406,6 +406,8 @@ Error Response * - Status Code - Description + * - 400 Bad Request + - A request parameter that cannot be decoded (for example ``?q=%ff``) was given. ``error.code`` is ``invalid_request``. * - 405 Method Not Allowed - An unsupported HTTP method was specified. * - 500 Internal Server Error diff --git a/en/15.10/install/upgrade.rst b/en/15.10/install/upgrade.rst index db331327c..ba462dd2c 100644 --- a/en/15.10/install/upgrade.rst +++ b/en/15.10/install/upgrade.rst @@ -1212,6 +1212,18 @@ The admin API answers a refusal with HTTP ``400`` and ``status`` ``1`` in the bo * - A user in the admin API whose password breaks the password policy (for example ``password.min.length``, default ``8``); a create request without a password; a ``confirm_password`` that differs from ``password`` - Saved; the user can log in with that password - ``400`` + * - ``GET /api/admin/log/file/{id}`` with a name that is not allowed for a log file (for example one that does not end with ``.log`` or ``.log.gz``), or with a file that is not in the log directory + - A name that is not allowed: ``200`` with an empty response + - ``400`` + * - An entry in the ``mapping`` dictionary without ``output``, added or updated through the admin API + - ``200`` (``id`` is ``0``); nothing is saved + - ``400`` + * - ``GET /api/admin/storage/list`` when the storage cannot be accessed, including when no storage client plugin is installed + - ``200`` (``status`` ``0``) with an empty list + - ``400``. ``message`` gives the cause and, when the plugin is missing, names the plugin to install + * - Repeated failed logins on the login form (``POST /login/login``) from one IP address, or for one user from one IP address, within a short time + - No limit + - Above the per-address or per-user limit (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), further logins from that address (for the per-user limit: for that user from that address) are refused for ``theme.api.login.lockout.seconds`` seconds, even with correct credentials. The response is the same login error as for wrong credentials. The limits and the lockout are shared with ``/api/v2/auth/login`` (see :doc:`../api/api-auth`) Rows of ``/api/v2/documents/all`` no longer carry ``score``. Up to 15.8 every document had its search score; 15.10 walks the whole result with a point in time and ``search_after``, which gives no score. @@ -1223,6 +1235,15 @@ accepted by ``POST``. The 15.8 documentation told you to use ``PUT``, but a ``mu never delivers the file, so in 15.8 as well as in 15.10 it fails with the validation error that the file is required. The ``PUT`` endpoints remain; use ``POST`` for uploads. +The following changes are not refusals, but can affect scripts and clients of the API and the admin UI. + +- The ``GET`` requests of the ``webauth`` and ``fileauth`` admin APIs (``/api/admin/webauth/settings``, ``/api/admin/webauth/setting/{id}`` and the same under ``fileauth``) no longer return the stored password. A ``PUT`` that omits the password or sends it blank keeps the stored password; a password that is not blank replaces it. +- A logged-in user is identified by the session, not by a ``userCode`` parameter or cookie that the request carries (for example for the favorite API). Anonymous users still use the parameter and the cookie. +- "Delete all" on the search list and crawling info screens of the admin UI needs the edit role (``admin-searchlist``, ``admin-crawlinginfo``). The request of a user who has only the view role (the role with the ``-view`` suffix) is refused. +- If you enabled ``parameterKey``, ``headerKey`` or ``cookieKey`` in the ``roleQueryHelper`` component of ``fess.xml`` but set no ``cipher``, and the encryption flag (``encryptedParameterValue``, ``encryptedHeaderValue`` or ``encryptedCookieValue``) is still ``true``, the default, 15.8 read the value as unencrypted role information. 15.10 ignores the value and logs a warning once. Set a ``cipher`` if the values are encrypted, or set the flag to ``false`` if they are meant to arrive unencrypted. +- A request whose ``Content-Type`` names a character set that the JVM does not know (for example ``charset=nope``) is handled like a request without a character set. ``/api/v2/search`` used to answer ``500`` (``internal_error``) for it. +- When an upload or download through the admin API fails for the ``kuromoji``, ``mapping``, ``stemmeroverride`` or ``synonym`` dictionary, the message now names that dictionary. In 15.8 it said "protwords file" for every one of them. + ``search_engine.type=cloud`` is deprecated ------------------------------------------ diff --git a/es/15.10/api/admin/api-admin-dict.rst b/es/15.10/api/admin/api-admin-dict.rst index a82cd7d60..43bf02a9e 100644 --- a/es/15.10/api/admin/api-admin-dict.rst +++ b/es/15.10/api/admin/api-admin-dict.rst @@ -421,7 +421,7 @@ Los campos del cuerpo de la solicitud de creación y actualización de elementos - ``token`` (requerido), ``segmentation`` (requerido), ``reading`` (requerido), ``pos`` (requerido) - ``kuromojiFile`` * - ``mapping`` - - ``inputs`` (requerido), ``output`` + - ``inputs`` (requerido), ``output`` (requerido) - ``charMappingFile`` * - ``protwords`` - ``input`` (requerido) diff --git a/es/15.10/api/admin/api-admin-log.rst b/es/15.10/api/admin/api-admin-log.rst index 167aab235..54fcf38b2 100644 --- a/es/15.10/api/admin/api-admin-log.rst +++ b/es/15.10/api/admin/api-admin-log.rst @@ -109,7 +109,11 @@ Descarga el contenido del archivo de registro especificado. En ``{id}`` se especifica el ``id`` devuelto en la lista (el valor del nombre de archivo codificado en Base64 URL) tal cual. La respuesta se devuelve como un flujo ``application/octet-stream``. Por razones de seguridad, solo se aceptan nombres que terminen en ``.log`` o ``.log.gz``; los nombres que contienen operaciones de ruta como ``..`` no son aceptados. -Si se especifica un nombre de archivo inexistente o un nombre no permitido como archivo de registro, se devuelve una respuesta vacía. +Si se especifica un nombre de archivo inexistente, un nombre no permitido como archivo de registro o un ``id`` que no es Base64 válido, se devuelve un error de validación (HTTP ``400``, con ``status`` igual a ``1`` en el cuerpo de la respuesta). + +.. note:: + + El ``id`` es Base64 seguro para URL (con ``-`` y ``_``). También se acepta un ``id`` con el alfabeto estándar (``+`` y ``/``), pero para evitar ambigüedades al colocarlo en una URL, use tal cual el ``id`` devuelto en la lista. Solicitud --------- @@ -123,6 +127,8 @@ Respuesta Flujo binario del archivo de registro (``Content-Type: application/octet-stream``). +Si no se encuentra ningún archivo de registro con el nombre especificado, se devuelve una respuesta de error con HTTP ``400`` y ``status`` igual a ``1`` en el cuerpo de la respuesta (no una respuesta vacía). + Ejemplos de Uso =============== diff --git a/es/15.10/api/admin/api-admin-storage.rst b/es/15.10/api/admin/api-admin-storage.rst index d89305bcb..79a990e12 100644 --- a/es/15.10/api/admin/api-admin-storage.rst +++ b/es/15.10/api/admin/api-admin-storage.rst @@ -10,7 +10,7 @@ Permite obtener el listado de archivos y directorios en el almacenamiento, así .. note:: - Esta API solo puede utilizarse si está instalado un plugin que proporcione el cliente de almacenamiento: ``fess-storage-s3`` para Amazon S3 y almacenamiento compatible con S3, o ``fess-storage-gcs`` para Google Cloud Storage. Los plugins no se incluyen en la distribución. Sin uno de ellos no hay cliente para el ``storage.type`` configurado y las solicitudes fallan. Instale el plugin en la página "Sistema" > "Plugin" de la pantalla de administración o con ``bin/fess-setup install plugin fess-storage-s3`` (``fess-storage-gcs`` para GCS). + Esta API solo puede utilizarse si está instalado un plugin que proporcione el cliente de almacenamiento: ``fess-storage-s3`` para Amazon S3 y almacenamiento compatible con S3, o ``fess-storage-gcs`` para Google Cloud Storage. Los plugins no se incluyen en la distribución. Sin uno de ellos no hay cliente para el ``storage.type`` configurado y las solicitudes fallan. Por ejemplo, ``GET /api/admin/storage/list`` no devuelve una lista vacía, sino un error con HTTP ``400`` (``status`` es ``1``), cuyo ``message`` contiene ``No storage client is registered as ...`` (después del prefijo «Storage Access Error») e indica el plugin que debe instalarse. Instale el plugin en la página "Sistema" > "Plugin" de la pantalla de administración o con ``bin/fess-setup install plugin fess-storage-s3`` (``fess-storage-gcs`` para GCS). URL Base ======== @@ -228,7 +228,7 @@ Los principales casos de error son los siguientes. * - Endpoint - Principales casos en que se produce un error * - Obtener listado de archivos y directorios - - Cuando el número de elementos supera el límite + - Cuando el número de elementos supera el límite, o cuando no se puede acceder al almacenamiento (incluido el caso en que no hay instalado ningún plugin de cliente de almacenamiento) * - Descargar un archivo - Cuando el ``id`` es inválido o la descarga falla * - Eliminar un archivo diff --git a/es/15.10/api/api-auth.rst b/es/15.10/api/api-auth.rst index 7b93c4a4d..795fa8375 100644 --- a/es/15.10/api/api-auth.rst +++ b/es/15.10/api/api-auth.rst @@ -145,6 +145,8 @@ Respuesta de error * - Código de estado - Descripción + * - 400 Bad Request + - Cuando se ha indicado un parámetro de la solicitud que no se puede decodificar (por ejemplo, ``?q=%ff``). El ``error.code`` es ``invalid_request``. * - 405 Method Not Allowed - Cuando se especifica un método HTTP no admitido. * - 500 Internal Server Error @@ -162,7 +164,7 @@ Endpoint ``/api/v2/auth/login`` ================== ==================================================== Inicia sesión con nombre de usuario y contraseña. -Cuando el inicio de sesión es exitoso, se rota el ID de sesión del servlet, se emite un nuevo token CSRF y se borran los cubos de límite de velocidad para la IP del cliente y el usuario objetivo. +Cuando el inicio de sesión es exitoso, se rota el ID de sesión del servlet, se emite un nuevo token CSRF. Además, se borra el registro de los intentos fallidos anteriores para la misma combinación de IP del cliente y nombre de usuario (el cubo por usuario). El cubo por IP no se borra, porque también cuenta los intentos realizados contra otros usuarios desde la misma IP; solo se devuelve la plaza que consumió este intento. El límite de velocidad se aplica en dos ejes: por IP del cliente y por usuario. Cuando se supera el límite por IP, se devuelve ``429 Too Many Requests`` junto con una cabecera ``Retry-After`` (en segundos). Cuando se supera el límite por usuario, se devuelve el mismo ``401 Unauthorized`` que para credenciales inválidas (sin cabecera ``Retry-After``), de modo que el estado del contador no pueda inferirse desde el exterior. @@ -183,10 +185,14 @@ Además, las rutas relativas al protocolo (que comienzan con ``//``) y las que c Los límites de velocidad para el inicio de sesión y el cambio de contraseña pueden configurarse con las siguientes propiedades (valor predeterminado entre paréntesis): - - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): Número máximo de intentos por minuto por dirección IP. Se aplica únicamente a ``/auth/login``. - - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): Número máximo de intentos por minuto por usuario. Se aplica tanto a ``/auth/login`` como a ``/auth/password``. + - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): Número máximo de intentos por minuto por dirección IP. Se aplica tanto a ``/auth/login`` como al formulario de inicio de sesión ``POST /login/login``, que comparten el mismo cubo. + - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): Número máximo de intentos por minuto por usuario. Se aplica a ``/auth/login`` y ``POST /login/login`` (que comparten un cubo por cada combinación de IP del cliente y nombre de usuario) y a ``/auth/password``. - ``theme.api.login.lockout.seconds`` (``900``): Duración del bloqueo (en segundos) una vez superado el límite. Se devuelve como valor de la cabecera ``Retry-After``. + El formulario de inicio de sesión (``POST /login/login``) comparte los cubos y el bloqueo con ``/auth/login``, por lo que los fallos en el formulario cuentan para el límite de ``/auth/login`` y viceversa. Cuando se supera el límite en el formulario, se trata como un error de inicio de sesión normal en lugar de ``429``. + + Detrás de un proxy inverso que no figura en ``rate.limit.trusted.proxies`` (valor predeterminado ``127.0.0.1,::1``), todos los clientes se tratan como una única dirección IP (la del proxy). Los inicios de sesión fallidos repetidos pueden entonces bloquear a todos los usuarios durante el tiempo de bloqueo. Añada la dirección del proxy a ``rate.limit.trusted.proxies`` para que la IP real del cliente se tome de ``X-Forwarded-For``. + Cuerpo de la solicitud (LoginRequest) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -284,12 +290,16 @@ Respuesta de error - Cuando la solicitud no es válida (incluye cuerpo de solicitud excesivo y ``Content-Type`` no admitido). * - 401 Unauthorized - Cuando las credenciales son inválidas. + * - 403 Forbidden + - Cuando la solicitud se ha bloqueado por ser de origen cruzado: su encabezado ``Origin`` (o ``Referer``) indica un origen no permitido. Es la comprobación básica que supera toda solicitud que modifica el estado y es independiente del token CSRF, que el inicio de sesión no necesita. * - 405 Method Not Allowed - Cuando se especifica un método HTTP no admitido. * - 429 Too Many Requests - Cuando se supera el límite de velocidad. La cabecera ``Retry-After`` indica los segundos que se deben esperar. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. Cierre de sesión ================ @@ -344,6 +354,8 @@ Respuesta de error * - Código de estado - Descripción + * - 400 Bad Request + - Cuando se ha indicado un parámetro de la solicitud que no se puede decodificar (por ejemplo, ``?q=%ff``). El ``error.code`` es ``invalid_request``. * - 403 Forbidden - Cuando el token CSRF está ausente o ha expirado. * - 405 Method Not Allowed @@ -456,3 +468,5 @@ Respuesta de error - Cuando se supera el límite de velocidad. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. diff --git a/es/15.10/api/api-cache.rst b/es/15.10/api/api-cache.rst index 06f8d2918..55afcff0f 100644 --- a/es/15.10/api/api-cache.rst +++ b/es/15.10/api/api-cache.rst @@ -96,5 +96,7 @@ Consulte :doc:`api-overview` para detalles del modelo de errores. Los estados HT - Cuando el método HTTP no está permitido. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. Tabla: Respuesta de error diff --git a/es/15.10/api/api-click.rst b/es/15.10/api/api-click.rst index 2c2dfe07d..591245ada 100644 --- a/es/15.10/api/api-click.rst +++ b/es/15.10/api/api-click.rst @@ -108,5 +108,7 @@ Consulte :doc:`api-overview` para detalles del modelo de errores. Los estados HT - El ``Content-Type`` no es ``application/json`` (se requiere UTF-8). * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. Tabla: Respuesta de error diff --git a/es/15.10/api/api-export.rst b/es/15.10/api/api-export.rst index f34cccb64..e859ca2c4 100644 --- a/es/15.10/api/api-export.rst +++ b/es/15.10/api/api-export.rst @@ -96,5 +96,7 @@ Respuesta de error - Cuando se supera el límite de solicitudes por minuto. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. Tabla: Respuesta de error diff --git a/es/15.10/api/api-health.rst b/es/15.10/api/api-health.rst index 09c1b9bdf..90bd54d5f 100644 --- a/es/15.10/api/api-health.rst +++ b/es/15.10/api/api-health.rst @@ -104,6 +104,8 @@ Consulte :doc:`api-overview` para detalles del modelo de errores. Los estados HT - Descripción * - 200 OK - Cuando el clúster está en estado ``GREEN`` o ``YELLOW`` y es accesible. El sobre de éxito incluye ``engine``. + * - 400 Bad Request + - Cuando se ha indicado un parámetro de la solicitud que no se puede decodificar (por ejemplo, ``?q=%ff``). El ``error.code`` es ``invalid_request``. * - 405 Method Not Allowed - Cuando el método HTTP no está permitido. * - 503 Service Unavailable diff --git a/es/15.10/api/api-label.rst b/es/15.10/api/api-label.rst index d79329f2c..62f2de29b 100644 --- a/es/15.10/api/api-label.rst +++ b/es/15.10/api/api-label.rst @@ -90,6 +90,8 @@ Consulte :doc:`api-overview` para detalles del modelo de errores. Los estados HT * - Código de estado - Descripción + * - 400 Bad Request + - Cuando se ha indicado un parámetro de la solicitud que no se puede decodificar (por ejemplo, ``?q=%ff``). El ``error.code`` es ``invalid_request``. * - 401 Unauthorized - Cuando se requiere autenticación (el inicio de sesión obligatorio está habilitado y el llamante es anónimo, o la solicitud lleva un token de acceso no registrado o caducado). ``error.code`` es ``auth_required``. * - 405 Method Not Allowed diff --git a/es/15.10/api/api-related.rst b/es/15.10/api/api-related.rst index fd1cdc0fa..adf4afd2a 100644 --- a/es/15.10/api/api-related.rst +++ b/es/15.10/api/api-related.rst @@ -78,6 +78,8 @@ Respuesta de error * - Código de estado - Descripción + * - 400 Bad Request + - Cuando se ha indicado un parámetro de la solicitud que no se puede decodificar (por ejemplo, ``?q=%ff``). El ``error.code`` es ``invalid_request``. * - 401 Unauthorized - Cuando se requiere autenticación (el inicio de sesión obligatorio está habilitado y el llamante es anónimo). ``error.code`` es ``auth_required``. * - 405 Method Not Allowed @@ -152,6 +154,8 @@ Respuesta de error * - Código de estado - Descripción + * - 400 Bad Request + - Cuando se ha indicado un parámetro de la solicitud que no se puede decodificar (por ejemplo, ``?q=%ff``). El ``error.code`` es ``invalid_request``. * - 401 Unauthorized - Cuando se requiere autenticación (el inicio de sesión obligatorio está habilitado y el llamante es anónimo). ``error.code`` es ``auth_required``. * - 405 Method Not Allowed diff --git a/es/15.10/api/api-search-history.rst b/es/15.10/api/api-search-history.rst index 6a83d4a5c..ee75c6afe 100644 --- a/es/15.10/api/api-search-history.rst +++ b/es/15.10/api/api-search-history.rst @@ -103,6 +103,8 @@ Respuesta de error - Cuando el método HTTP no está permitido. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. Tabla: Respuesta de error diff --git a/es/15.10/api/api-search.rst b/es/15.10/api/api-search.rst index 335e73d74..a5a695857 100644 --- a/es/15.10/api/api-search.rst +++ b/es/15.10/api/api-search.rst @@ -291,6 +291,8 @@ Consulte :doc:`api-overview` para detalles del modelo de errores. Los estados HT - Cuando el método HTTP no está permitido. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. Tabla: Respuesta de error diff --git a/es/15.10/api/api-suggest.rst b/es/15.10/api/api-suggest.rst index deb105f65..095011b44 100644 --- a/es/15.10/api/api-suggest.rst +++ b/es/15.10/api/api-suggest.rst @@ -127,3 +127,5 @@ Si la API de sugerencias falla, se devuelve el sobre de error común. Consulte : - Cuando se especifica un método HTTP no admitido. La cabecera ``Allow`` indica ``GET``. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. diff --git a/es/15.10/api/api-tag.rst b/es/15.10/api/api-tag.rst index 26881cb35..e50f67c47 100644 --- a/es/15.10/api/api-tag.rst +++ b/es/15.10/api/api-tag.rst @@ -404,6 +404,8 @@ etiquetas devuelven los siguientes estados HTTP. - Cuando el ``Content-Type`` no es compatible. * - 500 Internal Server Error - Cuando se produce un error interno del servidor. + * - 503 Service Unavailable + - Cuando el motor de búsqueda no ha podido atender la solicitud: no está accesible o la ha rechazado por falta de capacidad. ``error.code`` es ``service_unavailable`` y un encabezado ``Retry-After`` indica los segundos que hay que esperar (``5``). La solicitud en sí es correcta, así que vuelva a intentarlo tras una breve espera. Tabla: Respuesta de error diff --git a/es/15.10/api/api-uiconfig.rst b/es/15.10/api/api-uiconfig.rst index 24c8701eb..fcf5a59d6 100644 --- a/es/15.10/api/api-uiconfig.rst +++ b/es/15.10/api/api-uiconfig.rst @@ -406,6 +406,8 @@ Respuesta de error * - Código de estado - Descripción + * - 400 Bad Request + - Cuando se ha indicado un parámetro de la solicitud que no se puede decodificar (por ejemplo, ``?q=%ff``). El ``error.code`` es ``invalid_request``. * - 405 Method Not Allowed - Cuando se especifica un método HTTP no admitido. * - 500 Internal Server Error diff --git a/es/15.10/install/upgrade.rst b/es/15.10/install/upgrade.rst index e3c2b07fb..9ff3a8670 100644 --- a/es/15.10/install/upgrade.rst +++ b/es/15.10/install/upgrade.rst @@ -1260,6 +1260,18 @@ cuerpo. * - Un usuario de la API de administración cuya contraseña incumple la política de contraseñas (por ejemplo ``password.min.length``, por defecto ``8``); una creación sin contraseña; un ``confirm_password`` distinto de ``password`` - Se guarda; el usuario puede iniciar sesión con esa contraseña - ``400`` + * - ``GET /api/admin/log/file/{id}`` con un nombre no permitido para un archivo de registro (por ejemplo, que no termine en ``.log`` o ``.log.gz``), o con un archivo que no está en el directorio de registros + - Nombre no permitido: ``200`` con respuesta vacía + - ``400`` + * - Una entrada del diccionario ``mapping`` sin ``output``, creada o actualizada mediante la API de administración + - ``200`` (``id`` es ``0``); no se guarda nada + - ``400`` + * - ``GET /api/admin/storage/list`` cuando no se puede acceder al almacenamiento, incluido el caso en que no hay instalado ningún plugin de cliente de almacenamiento + - ``200`` (``status`` ``0``) con una lista vacía + - ``400``. ``message`` indica la causa y, si falta el plugin, el plugin que debe instalarse + * - Inicios de sesión fallidos repetidos en el formulario de inicio de sesión (``POST /login/login``) en poco tiempo, desde una misma dirección IP o para un mismo usuario desde una misma dirección IP + - Sin límite + - Al superar el límite por dirección o por usuario (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), los inicios de sesión posteriores desde esa dirección (con el límite por usuario: de ese usuario desde esa dirección) se rechazan durante ``theme.api.login.lockout.seconds`` segundos, incluso con credenciales correctas. La respuesta es el mismo error de inicio de sesión que con credenciales incorrectas. Los límites y el bloqueo se comparten con ``/api/v2/auth/login`` (consulte :doc:`../api/api-auth`) Las filas de ``/api/v2/documents/all`` ya no llevan ``score``. Hasta la 15.8 cada documento tenía su puntuación de búsqueda; la 15.10 recorre todo el resultado con un point in time y ``search_after``, que no @@ -1272,6 +1284,15 @@ Las subidas de archivos de la API de administración (los seis diccionarios, ``b error de validación de que el archivo es obligatorio. Los endpoints ``PUT`` siguen existiendo; utilice ``POST`` para las subidas. +Los siguientes cambios no son rechazos, pero pueden afectar a los scripts y clientes de la API y de la pantalla de administración. + +- Las solicitudes ``GET`` de las API de administración ``webauth`` y ``fileauth`` (``/api/admin/webauth/settings``, ``/api/admin/webauth/setting/{id}`` y los mismos endpoints de ``fileauth``) ya no devuelven la contraseña almacenada. Un ``PUT`` que omite la contraseña o la envía en blanco conserva la contraseña almacenada; una contraseña no vacía la sustituye. +- Un usuario con sesión iniciada se identifica por la sesión, no por un parámetro ``userCode`` ni una cookie que acompañe a la solicitud (por ejemplo, en la API de favoritos). Los usuarios anónimos siguen usando el parámetro y la cookie. +- «Eliminar todo» en las pantallas «Lista de búsqueda» e «Información de rastreo» de la pantalla de administración requiere el rol de edición (``admin-searchlist``, ``admin-crawlinginfo``). La solicitud de un usuario que solo tiene el rol de visualización (el rol con el sufijo ``-view``) se rechaza. +- Si activó ``parameterKey``, ``headerKey`` o ``cookieKey`` en el componente ``roleQueryHelper`` de ``fess.xml`` pero no configuró ningún ``cipher``, y el indicador de cifrado (``encryptedParameterValue``, ``encryptedHeaderValue`` o ``encryptedCookieValue``) sigue en ``true``, su valor predeterminado, la 15.8 leía el valor como información de roles sin cifrar. La 15.10 ignora el valor y registra una advertencia una sola vez. Configure un ``cipher`` si los valores están cifrados, o ponga el indicador en ``false`` si deben llegar sin cifrar. +- Una solicitud cuyo ``Content-Type`` indica un juego de caracteres que la JVM no conoce (por ejemplo, ``charset=nope``) se trata como una solicitud sin juego de caracteres. Antes, ``/api/v2/search`` respondía ``500`` (``internal_error``). +- Cuando falla una carga o descarga mediante la API de administración del diccionario ``kuromoji``, ``mapping``, ``stemmeroverride`` o ``synonym``, el mensaje ahora nombra ese diccionario. En la 15.8 decía «protwords file» en todos ellos. + ``search_engine.type=cloud`` está obsoleto ------------------------------------------ diff --git a/fr/15.10/api/admin/api-admin-dict.rst b/fr/15.10/api/admin/api-admin-dict.rst index cfebe87de..7ec32664d 100644 --- a/fr/15.10/api/admin/api-admin-dict.rst +++ b/fr/15.10/api/admin/api-admin-dict.rst @@ -421,7 +421,7 @@ Les champs du corps de requête de création/mise à jour d'une entrée de dicti - ``token`` (requis), ``segmentation`` (requis), ``reading`` (requis), ``pos`` (requis) - ``kuromojiFile`` * - ``mapping`` - - ``inputs`` (requis), ``output`` + - ``inputs`` (requis), ``output`` (requis) - ``charMappingFile`` * - ``protwords`` - ``input`` (requis) diff --git a/fr/15.10/api/admin/api-admin-log.rst b/fr/15.10/api/admin/api-admin-log.rst index 5d240fc22..8e71a1d16 100644 --- a/fr/15.10/api/admin/api-admin-log.rst +++ b/fr/15.10/api/admin/api-admin-log.rst @@ -111,7 +111,11 @@ Télécharge le contenu du fichier journal spécifié. Pour ``{id}``, indiquez tel quel l'``id`` retourné lors de l'obtention de la liste (la valeur du nom de fichier encodée en Base64 URL). La réponse est renvoyée sous forme de flux ``application/octet-stream``. Pour des raisons de sécurité, seuls les noms se terminant par ``.log`` ou ``.log.gz`` sont acceptés ; les noms contenant des séquences de manipulation de chemin telles que ``..`` sont rejetés. -Si vous spécifiez un nom de fichier inexistant ou un nom non autorisé en tant que fichier journal, une réponse vide est renvoyée. +Si vous spécifiez un nom de fichier inexistant, un nom non autorisé en tant que fichier journal ou un ``id`` qui n'est pas du Base64 valide, une erreur de validation est renvoyée (HTTP ``400``, avec ``status`` égal à ``1`` dans le corps de la réponse). + +.. note:: + + L'``id`` est du Base64 compatible URL (utilisant ``-`` et ``_``). Un ``id`` utilisant l'alphabet standard (``+`` et ``/``) est également accepté, mais pour éviter toute ambiguïté lorsqu'il est placé dans une URL, utilisez tel quel l'``id`` retourné lors de l'obtention de la liste. Requête ------- @@ -125,6 +129,8 @@ Réponse Flux binaire du fichier journal (``Content-Type: application/octet-stream``). +Si aucun fichier journal portant le nom spécifié n'est trouvé, une réponse d'erreur avec HTTP ``400`` et ``status`` égal à ``1`` dans le corps de la réponse est renvoyée (et non une réponse vide). + Exemples d'utilisation ====================== diff --git a/fr/15.10/api/admin/api-admin-storage.rst b/fr/15.10/api/admin/api-admin-storage.rst index 924daa0b5..465e252aa 100644 --- a/fr/15.10/api/admin/api-admin-storage.rst +++ b/fr/15.10/api/admin/api-admin-storage.rst @@ -10,7 +10,7 @@ Elle permet de lister les fichiers et répertoires dans le stockage, ainsi que d .. note:: - Cette API n'est utilisable que si un plugin fournissant le client de stockage est installé : ``fess-storage-s3`` pour Amazon S3 et les stockages compatibles S3, ou ``fess-storage-gcs`` pour Google Cloud Storage. Les plugins ne sont pas inclus dans la distribution. Sans l'un d'eux, il n'existe aucun client pour le ``storage.type`` configuré et les requêtes échouent. Installez le plugin depuis la page « Système » > « Plugin » de l'écran d'administration ou avec ``bin/fess-setup install plugin fess-storage-s3`` (``fess-storage-gcs`` pour GCS). + Cette API n'est utilisable que si un plugin fournissant le client de stockage est installé : ``fess-storage-s3`` pour Amazon S3 et les stockages compatibles S3, ou ``fess-storage-gcs`` pour Google Cloud Storage. Les plugins ne sont pas inclus dans la distribution. Sans l'un d'eux, il n'existe aucun client pour le ``storage.type`` configuré et les requêtes échouent. Par exemple, ``GET /api/admin/storage/list`` ne renvoie pas une liste vide mais une erreur avec HTTP ``400`` (``status`` vaut ``1``), dont le ``message`` contient ``No storage client is registered as ...`` (après le préfixe « Storage Access Error ») et indique le plugin à installer. Installez le plugin depuis la page « Système » > « Plugin » de l'écran d'administration ou avec ``bin/fess-setup install plugin fess-storage-s3`` (``fess-storage-gcs`` pour GCS). URL de base =========== @@ -227,7 +227,7 @@ Les principaux cas d'erreur sont les suivants. * - Endpoint - Principaux cas d'erreur * - Obtention de la liste des fichiers et répertoires - - Lorsque le nombre d'éléments récupérés dépasse la limite maximale + - Lorsque le nombre d'éléments récupérés dépasse la limite maximale, ou lorsque le stockage est inaccessible (y compris lorsqu'aucun plugin de client de stockage n'est installé) * - Téléchargement d'un fichier - Lorsque l'``id`` est invalide ou que le téléchargement échoue * - Suppression d'un fichier diff --git a/fr/15.10/api/api-auth.rst b/fr/15.10/api/api-auth.rst index ff0a84a42..826bad382 100644 --- a/fr/15.10/api/api-auth.rst +++ b/fr/15.10/api/api-auth.rst @@ -145,6 +145,8 @@ Réponse d'erreur * - Code de statut - Description + * - 400 Bad Request + - Un paramètre de requête impossible à décoder (par exemple ``?q=%ff``) a été fourni. ``error.code`` vaut ``invalid_request``. * - 405 Method Not Allowed - Une méthode HTTP non prise en charge a été spécifiée. * - 500 Internal Server Error @@ -162,7 +164,7 @@ Point de terminaison ``/api/v2/auth/login`` ==================== ==================================================== Se connecte avec un nom d'utilisateur et un mot de passe. -En cas de succès, l'identifiant de session du servlet est renouvelé, un nouveau jeton CSRF est émis, et les buckets de limite de débit de l'IP appelante et de l'utilisateur cible sont réinitialisés. +En cas de succès, l'identifiant de session du servlet est renouvelé, un nouveau jeton CSRF est émis. De plus, l'enregistrement des tentatives échouées antérieures pour la même combinaison d'IP appelante et de nom d'utilisateur (le bucket par utilisateur) est réinitialisé. Le bucket par IP n'est pas réinitialisé, car il compte aussi les tentatives visant d'autres utilisateurs depuis la même IP ; seul l'emplacement consommé par cette tentative est restitué. La limitation de débit est appliquée selon deux axes : par IP appelante et par utilisateur. Lorsque la limite par IP est dépassée, ``429 Too Many Requests`` est retourné accompagné d'un en-tête ``Retry-After`` (en secondes). Lorsque la limite par utilisateur est dépassée, le même ``401 Unauthorized`` que pour des informations d'identification invalides est retourné (sans en-tête ``Retry-After``), afin que l'état du compteur ne puisse pas être déduit de l'extérieur. @@ -183,10 +185,14 @@ De plus, les chemins relatifs aux protocoles (commençant par ``//``) et les che Les limites de débit pour la connexion et le changement de mot de passe peuvent être configurées avec les propriétés suivantes (valeurs par défaut entre parenthèses) : - - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``) : Nombre maximal de tentatives par minute par adresse IP. S'applique uniquement à ``/auth/login``. - - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``) : Nombre maximal de tentatives par minute par utilisateur. S'applique à la fois à ``/auth/login`` et à ``/auth/password``. + - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``) : Nombre maximal de tentatives par minute par adresse IP. S'applique à la fois à ``/auth/login`` et au formulaire de connexion ``POST /login/login``, qui partagent le même bucket. + - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``) : Nombre maximal de tentatives par minute par utilisateur. S'applique à ``/auth/login`` et ``POST /login/login`` (qui partagent un bucket pour chaque combinaison d'IP appelante et de nom d'utilisateur) ainsi qu'à ``/auth/password``. - ``theme.api.login.lockout.seconds`` (``900``) : Durée de verrouillage (en secondes) après dépassement de la limite. Retournée comme valeur de l'en-tête ``Retry-After``. + Le formulaire de connexion (``POST /login/login``) partage les buckets et le verrouillage avec ``/auth/login`` : les échecs sur le formulaire comptent donc pour la limite de ``/auth/login`` et inversement. Lorsque la limite est dépassée sur le formulaire, elle est traitée comme une erreur de connexion ordinaire et non comme un ``429``. + + Derrière un proxy inverse absent de ``rate.limit.trusted.proxies`` (valeur par défaut ``127.0.0.1,::1``), tous les clients sont traités comme une seule adresse IP (celle du proxy). Des échecs de connexion répétés peuvent alors verrouiller tous les utilisateurs pendant la durée du verrouillage. Ajoutez l'adresse du proxy à ``rate.limit.trusted.proxies`` afin que l'IP réelle du client soit prise dans ``X-Forwarded-For``. + Corps de la requête (LoginRequest) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -284,12 +290,16 @@ Réponse d'erreur - La requête est incorrecte (corps trop grand ou ``Content-Type`` non pris en charge inclus). * - 401 Unauthorized - Les informations d'authentification sont incorrectes. + * - 403 Forbidden + - La requête a été bloquée comme inter-sites : son en-tête ``Origin`` (ou ``Referer``) désigne une origine non autorisée. C'est le contrôle de base que passe toute requête modifiant l'état ; il est distinct du jeton CSRF, dont la connexion n'a pas besoin. * - 405 Method Not Allowed - Une méthode HTTP non prise en charge a été spécifiée. * - 429 Too Many Requests - Limite de débit dépassée. L'en-tête ``Retry-After`` indique le nombre de secondes d'attente. * - 500 Internal Server Error - Une erreur interne s'est produite sur le serveur. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. Déconnexion =========== @@ -344,6 +354,8 @@ Réponse d'erreur * - Code de statut - Description + * - 400 Bad Request + - Un paramètre de requête impossible à décoder (par exemple ``?q=%ff``) a été fourni. ``error.code`` vaut ``invalid_request``. * - 403 Forbidden - Jeton CSRF manquant ou expiré. * - 405 Method Not Allowed @@ -456,3 +468,5 @@ Réponse d'erreur - Limite de débit dépassée. * - 500 Internal Server Error - Une erreur interne s'est produite sur le serveur. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. diff --git a/fr/15.10/api/api-cache.rst b/fr/15.10/api/api-cache.rst index 03f905db6..3a4381855 100644 --- a/fr/15.10/api/api-cache.rst +++ b/fr/15.10/api/api-cache.rst @@ -96,5 +96,7 @@ Pour le détail du modèle d'erreur, voir :doc:`api-overview`. Les statuts HTTP - La méthode HTTP n'est pas autorisée. * - 500 Internal Server Error - Une erreur interne s'est produite sur le serveur. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. Tableau : Réponses d'erreur diff --git a/fr/15.10/api/api-click.rst b/fr/15.10/api/api-click.rst index 391bdfbdc..0e6c16572 100644 --- a/fr/15.10/api/api-click.rst +++ b/fr/15.10/api/api-click.rst @@ -108,5 +108,7 @@ Pour le détail du modèle d'erreur, voir :doc:`api-overview`. Les statuts HTTP - Le ``Content-Type`` n'est pas ``application/json`` (UTF-8 est requis). * - 500 Internal Server Error - Une erreur interne s'est produite sur le serveur. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. Tableau : Réponses d'erreur diff --git a/fr/15.10/api/api-export.rst b/fr/15.10/api/api-export.rst index 7b71a645d..0197a5b66 100644 --- a/fr/15.10/api/api-export.rst +++ b/fr/15.10/api/api-export.rst @@ -96,5 +96,7 @@ Réponses d'erreur - Lorsque la limite de requêtes par minute est dépassée. * - 500 Internal Server Error - Lorsqu'une erreur interne du serveur se produit. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. Tableau : Réponses d'erreur diff --git a/fr/15.10/api/api-health.rst b/fr/15.10/api/api-health.rst index 4f5c9327f..ef67a063e 100644 --- a/fr/15.10/api/api-health.rst +++ b/fr/15.10/api/api-health.rst @@ -104,6 +104,8 @@ Pour le détail du modèle d'erreur, voir :doc:`api-overview`. Les statuts HTTP - Description * - 200 OK - Le cluster est ``GREEN`` ou ``YELLOW`` et joignable. L'enveloppe de succès contient ``engine``. + * - 400 Bad Request + - Un paramètre de requête impossible à décoder (par exemple ``?q=%ff``) a été fourni. ``error.code`` vaut ``invalid_request``. * - 405 Method Not Allowed - La méthode HTTP n'est pas autorisée. * - 503 Service Unavailable diff --git a/fr/15.10/api/api-label.rst b/fr/15.10/api/api-label.rst index cfa3cf059..b1f6fbcb0 100644 --- a/fr/15.10/api/api-label.rst +++ b/fr/15.10/api/api-label.rst @@ -90,6 +90,8 @@ Pour le détail du modèle d'erreur, voir :doc:`api-overview`. Les statuts HTTP * - Code de statut - Description + * - 400 Bad Request + - Un paramètre de requête impossible à décoder (par exemple ``?q=%ff``) a été fourni. ``error.code`` vaut ``invalid_request``. * - 401 Unauthorized - Authentification requise (connexion obligatoire activée avec un appelant anonyme, ou requête portant un jeton d'accès non enregistré ou expiré). ``error.code`` vaut ``auth_required``. * - 405 Method Not Allowed diff --git a/fr/15.10/api/api-related.rst b/fr/15.10/api/api-related.rst index e8fc2ebd9..429200c73 100644 --- a/fr/15.10/api/api-related.rst +++ b/fr/15.10/api/api-related.rst @@ -78,6 +78,8 @@ Réponse d'erreur * - Code de statut - Description + * - 400 Bad Request + - Un paramètre de requête impossible à décoder (par exemple ``?q=%ff``) a été fourni. ``error.code`` vaut ``invalid_request``. * - 401 Unauthorized - Authentification requise (connexion obligatoire activée avec un appelant anonyme). ``error.code`` vaut ``auth_required``. * - 405 Method Not Allowed @@ -152,6 +154,8 @@ Réponse d'erreur * - Code de statut - Description + * - 400 Bad Request + - Un paramètre de requête impossible à décoder (par exemple ``?q=%ff``) a été fourni. ``error.code`` vaut ``invalid_request``. * - 401 Unauthorized - Authentification requise (connexion obligatoire activée avec un appelant anonyme). ``error.code`` vaut ``auth_required``. * - 405 Method Not Allowed diff --git a/fr/15.10/api/api-search-history.rst b/fr/15.10/api/api-search-history.rst index 95b4787cb..4d67be3e8 100644 --- a/fr/15.10/api/api-search-history.rst +++ b/fr/15.10/api/api-search-history.rst @@ -104,6 +104,8 @@ Réponses d'erreur - Lorsque la méthode HTTP n'est pas autorisée. * - 500 Internal Server Error - Lorsqu'une erreur interne du serveur se produit. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. Tableau : Réponses d'erreur diff --git a/fr/15.10/api/api-search.rst b/fr/15.10/api/api-search.rst index 42baefe10..ea1176779 100644 --- a/fr/15.10/api/api-search.rst +++ b/fr/15.10/api/api-search.rst @@ -291,6 +291,8 @@ Pour le détail du modèle d'erreur, voir :doc:`api-overview`. Les statuts HTTP - La méthode HTTP n'est pas autorisée. * - 500 Internal Server Error - Une erreur interne s'est produite sur le serveur. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. Tableau : Réponses d'erreur diff --git a/fr/15.10/api/api-suggest.rst b/fr/15.10/api/api-suggest.rst index 997846d6b..921cba5e4 100644 --- a/fr/15.10/api/api-suggest.rst +++ b/fr/15.10/api/api-suggest.rst @@ -127,3 +127,5 @@ En cas d'échec de l'API de suggestions, l'enveloppe d'erreur commune est retour - Une méthode HTTP non prise en charge a été spécifiée. L'en-tête ``Allow`` indique ``GET``. * - 500 Internal Server Error - Une erreur interne s'est produite sur le serveur. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. diff --git a/fr/15.10/api/api-tag.rst b/fr/15.10/api/api-tag.rst index 7c88c38f6..4abb33afe 100644 --- a/fr/15.10/api/api-tag.rst +++ b/fr/15.10/api/api-tag.rst @@ -399,6 +399,8 @@ statuts HTTP suivants. - Lorsque le ``Content-Type`` n'est pas pris en charge. * - 500 Internal Server Error - Lorsqu'une erreur interne du serveur se produit. + * - 503 Service Unavailable + - Le moteur de recherche n'a pas pu prendre la requête en charge : il est injoignable ou a refusé la requête faute de capacité. ``error.code`` vaut ``service_unavailable`` et un en-tête ``Retry-After`` indique le nombre de secondes à attendre (``5``). La requête elle-même est correcte : réessayez après une courte attente. Tableau : Réponses d'erreur diff --git a/fr/15.10/api/api-uiconfig.rst b/fr/15.10/api/api-uiconfig.rst index 5ab48b5ed..02280fa0e 100644 --- a/fr/15.10/api/api-uiconfig.rst +++ b/fr/15.10/api/api-uiconfig.rst @@ -406,6 +406,8 @@ Réponse d'erreur * - Code de statut - Description + * - 400 Bad Request + - Un paramètre de requête impossible à décoder (par exemple ``?q=%ff``) a été fourni. ``error.code`` vaut ``invalid_request``. * - 405 Method Not Allowed - Une méthode HTTP non prise en charge a été spécifiée. * - 500 Internal Server Error diff --git a/fr/15.10/install/upgrade.rst b/fr/15.10/install/upgrade.rst index f18cc4b6f..9f4144d4d 100644 --- a/fr/15.10/install/upgrade.rst +++ b/fr/15.10/install/upgrade.rst @@ -1272,6 +1272,18 @@ le corps. * - Un utilisateur de l'API d'administration dont le mot de passe enfreint la politique de mot de passe (par exemple ``password.min.length``, ``8`` par défaut) ; une création sans mot de passe ; un ``confirm_password`` différent de ``password`` - Enregistré ; l'utilisateur peut se connecter avec ce mot de passe - ``400`` + * - ``GET /api/admin/log/file/{id}`` avec un nom non autorisé pour un fichier journal (par exemple ne se terminant pas par ``.log`` ou ``.log.gz``), ou avec un fichier qui ne se trouve pas dans le répertoire des journaux + - Nom non autorisé : ``200`` avec une réponse vide + - ``400`` + * - Une entrée du dictionnaire ``mapping`` sans ``output``, ajoutée ou mise à jour via l'API d'administration + - ``200`` (``id`` vaut ``0``) ; rien n'est enregistré + - ``400`` + * - ``GET /api/admin/storage/list`` lorsque le stockage est inaccessible, y compris lorsqu'aucun plugin de client de stockage n'est installé + - ``200`` (``status`` ``0``) avec une liste vide + - ``400``. ``message`` indique la cause et, si le plugin est absent, le plugin à installer + * - Connexions échouées répétées sur le formulaire de connexion (``POST /login/login``) en peu de temps, depuis une même adresse IP ou pour un même utilisateur depuis une même adresse IP + - Aucune limite + - Au-delà de la limite par adresse ou par utilisateur (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), les connexions suivantes depuis cette adresse (pour la limite par utilisateur : de cet utilisateur depuis cette adresse) sont refusées pendant ``theme.api.login.lockout.seconds`` secondes, même avec des identifiants corrects. La réponse est la même erreur de connexion qu'avec des identifiants erronés. Les limites et le verrouillage sont partagés avec ``/api/v2/auth/login`` (voir :doc:`../api/api-auth`) Les lignes de ``/api/v2/documents/all`` ne portent plus ``score``. Jusqu'à la 15.8, chaque document avait son score de recherche ; la 15.10 parcourt tout le résultat avec un point in time et ``search_after``, ce qui @@ -1284,6 +1296,15 @@ Les envois de fichiers de l'API d'administration (les six dictionnaires, ``badwo validation indiquant que le fichier est obligatoire. Les points de terminaison ``PUT`` subsistent ; utilisez ``POST`` pour les envois. +Les modifications suivantes ne sont pas des refus, mais peuvent affecter les scripts et les clients de l'API et de l'écran d'administration. + +- Les requêtes ``GET`` des API d'administration ``webauth`` et ``fileauth`` (``/api/admin/webauth/settings``, ``/api/admin/webauth/setting/{id}`` et les mêmes points d'accès sous ``fileauth``) ne renvoient plus le mot de passe enregistré. Un ``PUT`` qui omet le mot de passe ou l'envoie vide conserve le mot de passe enregistré ; un mot de passe non vide le remplace. +- Un utilisateur connecté est identifié par la session, et non par un paramètre ``userCode`` ou un cookie que porte la requête (par exemple pour l'API des favoris). Les utilisateurs anonymes continuent d'utiliser le paramètre et le cookie. +- « Tout supprimer » sur les écrans « Liste de recherche » et « Informations d'exploration » de l'écran d'administration exige le rôle d'édition (``admin-searchlist``, ``admin-crawlinginfo``). La requête d'un utilisateur qui n'a que le rôle de consultation (le rôle portant le suffixe ``-view``) est refusée. +- Si vous avez activé ``parameterKey``, ``headerKey`` ou ``cookieKey`` dans le composant ``roleQueryHelper`` de ``fess.xml`` sans définir de ``cipher``, et que l'indicateur de chiffrement (``encryptedParameterValue``, ``encryptedHeaderValue`` ou ``encryptedCookieValue``) est resté à ``true``, sa valeur par défaut, la 15.8 lisait la valeur comme une information de rôle non chiffrée. La 15.10 ignore la valeur et écrit un avertissement une seule fois dans le journal. Définissez un ``cipher`` si les valeurs sont chiffrées, ou mettez l'indicateur à ``false`` si elles doivent arriver non chiffrées. +- Une requête dont le ``Content-Type`` indique un jeu de caractères inconnu de la JVM (par exemple ``charset=nope``) est traitée comme une requête sans jeu de caractères. Auparavant, ``/api/v2/search`` répondait ``500`` (``internal_error``). +- Lorsqu'un envoi ou un téléchargement via l'API d'administration échoue pour le dictionnaire ``kuromoji``, ``mapping``, ``stemmeroverride`` ou ``synonym``, le message nomme désormais ce dictionnaire. En 15.8, il indiquait « protwords file » pour chacun d'eux. + ``search_engine.type=cloud`` est obsolète ----------------------------------------- diff --git a/ja/15.10/api/admin/api-admin-dict.rst b/ja/15.10/api/admin/api-admin-dict.rst index 13658c4b0..d8540a1f8 100644 --- a/ja/15.10/api/admin/api-admin-dict.rst +++ b/ja/15.10/api/admin/api-admin-dict.rst @@ -422,7 +422,7 @@ Dict APIは、|Fess| の辞書を管理するためのAPIです。 - ``token`` （必須）、 ``segmentation`` （必須）、 ``reading`` （必須）、 ``pos`` （必須） - ``kuromojiFile`` * - ``mapping`` - - ``inputs`` （必須）、 ``output`` + - ``inputs`` （必須）、 ``output`` （必須） - ``charMappingFile`` * - ``protwords`` - ``input`` （必須） diff --git a/ja/15.10/api/admin/api-admin-log.rst b/ja/15.10/api/admin/api-admin-log.rst index 8da4673b0..9da3212f5 100644 --- a/ja/15.10/api/admin/api-admin-log.rst +++ b/ja/15.10/api/admin/api-admin-log.rst @@ -110,7 +110,11 @@ Log APIは、|Fess| のログファイルを参照・ダウンロードするた ``{id}`` には一覧取得で返された ``id`` （ファイル名を Base64 URL エンコードした値）をそのまま指定します。 レスポンスは ``application/octet-stream`` のストリームとして返されます。 セキュリティのため、``.log`` または ``.log.gz`` で終わる名前のみが対象となり、``..`` などのパス操作を含む名前は受け付けません。 -存在しないファイル名やログファイルとして許可されない名前を指定した場合は、空のレスポンスが返されます。 +存在しないファイル名やログファイルとして許可されない名前、および Base64 として不正な ``id`` を指定した場合は、検証エラー（HTTP ``400`` 、レスポンス本文の ``status`` は ``1`` ）が返されます。 + +.. note:: + + ``id`` は URL-safe Base64（ ``-`` と ``_`` を使用）です。標準アルファベット（ ``+`` と ``/`` ）の ``id`` も受け付けますが、URL に含める際の曖昧さを避けるため、一覧取得で返された ``id`` をそのまま使用してください。 リクエスト ---------- @@ -124,6 +128,8 @@ Log APIは、|Fess| のログファイルを参照・ダウンロードするた ログファイルのバイナリストリーム（``Content-Type: application/octet-stream``）。 +指定した名前のログファイルが見つからない場合は、HTTP ``400`` で、レスポンス本文の ``status`` が ``1`` のエラーレスポンスが返されます（空のレスポンスではありません）。 + 使用例 ====== diff --git a/ja/15.10/api/admin/api-admin-storage.rst b/ja/15.10/api/admin/api-admin-storage.rst index 9457110d6..75bf7a57f 100644 --- a/ja/15.10/api/admin/api-admin-storage.rst +++ b/ja/15.10/api/admin/api-admin-storage.rst @@ -12,7 +12,7 @@ Storage APIは、|Fess| のオブジェクトストレージを管理するた このAPIを使うには、ストレージクライアントを提供するプラグイン（Amazon S3 と S3 互換ストレージは ``fess-storage-s3`` 、 Google Cloud Storage は ``fess-storage-gcs`` ）が導入されている必要があります。プラグインは配布物に同梱されていません。\ - 導入されていないと、 ``storage.type`` に対応するクライアントがないため、リクエストは失敗します。\ + 導入されていないと、 ``storage.type`` に対応するクライアントがないため、リクエストは失敗します。たとえば ``GET /api/admin/storage/list`` は、空の一覧ではなく、HTTP ``400`` （ ``status`` は ``1`` ）で、 ``message`` に ``No storage client is registered as ...`` を含み、導入するプラグインを示すエラーを返します。\ 管理画面の「システム > プラグイン」ページ、または ``bin/fess-setup install plugin fess-storage-s3`` （GCS の場合は ``fess-storage-gcs`` ）で導入してください。 ベースURL @@ -231,7 +231,7 @@ Storage APIを含む Admin API のすべてのエンドポイントには、ア * - エンドポイント - エラーが発生する主なケース * - ファイル・ディレクトリ一覧取得 - - 取得件数が上限を超えた場合 + - 取得件数が上限を超えた場合、またはストレージにアクセスできない場合（ストレージクライアントのプラグインが導入されていない場合を含む） * - ファイルのダウンロード - ``id`` が不正な場合、またはダウンロードに失敗した場合 * - ファイルの削除 diff --git a/ja/15.10/api/api-auth.rst b/ja/15.10/api/api-auth.rst index 4362f79fa..fcc89f2d3 100644 --- a/ja/15.10/api/api-auth.rst +++ b/ja/15.10/api/api-auth.rst @@ -145,6 +145,8 @@ HTTPメソッド GET * - ステータスコード - 説明 + * - 400 Bad Request + - デコードできないリクエストパラメーター（ ``?q=%ff`` など）が指定された場合。 ``error.code`` は ``invalid_request`` です。 * - 405 Method Not Allowed - サポートされていない HTTP メソッドが指定された場合。 * - 500 Internal Server Error @@ -162,7 +164,7 @@ HTTPメソッド POST ================== ==================================================== ユーザー名とパスワードでログインします。 -ログイン成功時には、サーブレットのセッションIDがローテーションされ、新しい CSRF トークンが発行され、呼び出し元 IP と対象ユーザーのレート制限バケットがクリアされます。 +ログイン成功時には、サーブレットのセッションIDがローテーションされ、新しい CSRF トークンが発行されます。また、同じ呼び出し元 IP とユーザー名の組でそれまでに失敗した試行の記録（ユーザー単位のバケット）はクリアされます。IP 単位のバケットは、同じ IP から他のユーザーに対して行われた試行も数えているためクリアされず、この試行が消費した 1 回分だけが戻されます。 レート制限は、呼び出し元 IP 単位とユーザー単位の2系統で行われます。IP 単位の上限を超えた場合は ``429 Too Many Requests`` を返し、 ``Retry-After`` ヘッダー（秒）を付与します。ユーザー単位の上限を超えた場合は、カウンターの状態が外部から推測されることを防ぐため、認証情報が不正な場合と同じ ``401 Unauthorized`` を（ ``Retry-After`` なしで）返します。 @@ -183,10 +185,14 @@ HTTPメソッド POST ログインとパスワード変更のレート制限は、以下のプロパティで設定できます（かっこ内は既定値）。 - - ``theme.api.login.rate.limit.per.ip.per.minute`` （ ``10`` ）: IP アドレス単位の毎分あたりの試行回数上限。 ``/auth/login`` のみに適用されます。 - - ``theme.api.login.rate.limit.per.user.per.minute`` （ ``5`` ）: ユーザー単位の毎分あたりの試行回数上限。 ``/auth/login`` と ``/auth/password`` の両方に適用されます。 + - ``theme.api.login.rate.limit.per.ip.per.minute`` （ ``10`` ）: IP アドレス単位の毎分あたりの試行回数上限。 ``/auth/login`` と、ログインフォームの ``POST /login/login`` の両方に適用され、両者は同じバケットを共有します。 + - ``theme.api.login.rate.limit.per.user.per.minute`` （ ``5`` ）: ユーザー単位の毎分あたりの試行回数上限。 ``/auth/login`` と ``POST /login/login`` （呼び出し元 IP とユーザー名の組ごとに同じバケットを共有）、および ``/auth/password`` に適用されます。 - ``theme.api.login.lockout.seconds`` （ ``900`` ）: 上限を超えた後のロックアウト時間（秒）。 ``Retry-After`` ヘッダーの値として返されます。 + ログインフォーム（ ``POST /login/login`` ）は ``/auth/login`` と同じバケットとロックアウトを共有しているため、フォームでの失敗も ``/auth/login`` の上限に数えられ、その逆も同様です。フォームで上限を超えた場合は、 ``429`` ではなく通常のログインエラーとして扱われます。 + + ``rate.limit.trusted.proxies`` （既定値は ``127.0.0.1,::1`` ）に含まれないリバースプロキシの背後では、すべてのクライアントが同じ IP アドレス（プロキシのアドレス）として扱われます。そのため、失敗したログインが続くと、ロックアウト時間の間、全ユーザーがログインできなくなる場合があります。プロキシのアドレスを ``rate.limit.trusted.proxies`` に追加し、 ``X-Forwarded-For`` から実際のクライアント IP が使われるようにしてください。 + リクエストボディ (LoginRequest) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -284,12 +290,16 @@ Content-Type は ``application/json`` （文字コードは UTF-8）です。リ - リクエストが不正な場合（過大なリクエストボディや非対応の ``Content-Type`` を含む）。 * - 401 Unauthorized - 認証情報が不正な場合。 + * - 403 Forbidden + - ``Origin`` （または ``Referer`` ）ヘッダーが許可されていないオリジンを示し、クロスサイトのリクエストとしてブロックされた場合。状態を変更するリクエスト共通の基本チェックで、ログインに不要な CSRF トークンとは別のものです。 * - 405 Method Not Allowed - サポートされていない HTTP メソッドが指定された場合。 * - 429 Too Many Requests - レート制限を超えた場合。 ``Retry-After`` ヘッダーに待機すべき秒数が示されます。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 ログアウト ======== @@ -344,6 +354,8 @@ HTTPメソッド POST * - ステータスコード - 説明 + * - 400 Bad Request + - デコードできないリクエストパラメーター（ ``?q=%ff`` など）が指定された場合。 ``error.code`` は ``invalid_request`` です。 * - 403 Forbidden - CSRF トークンが欠落・失効している場合。 * - 405 Method Not Allowed @@ -456,3 +468,5 @@ Content-Type は ``application/json`` （文字コードは UTF-8）です。リ - レート制限を超えた場合。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 diff --git a/ja/15.10/api/api-cache.rst b/ja/15.10/api/api-cache.rst index 292d1112e..6b4d7f8f3 100644 --- a/ja/15.10/api/api-cache.rst +++ b/ja/15.10/api/api-cache.rst @@ -96,5 +96,7 @@ HTTPメソッド GET - HTTP メソッドが許可されていない場合。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 表: エラーレスポンス diff --git a/ja/15.10/api/api-click.rst b/ja/15.10/api/api-click.rst index 498a97cdd..7ac24c568 100644 --- a/ja/15.10/api/api-click.rst +++ b/ja/15.10/api/api-click.rst @@ -108,5 +108,7 @@ HTTPメソッド POST - ``Content-Type`` が ``application/json`` でない場合（UTF-8 が必要です）。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 表: エラーレスポンス diff --git a/ja/15.10/api/api-export.rst b/ja/15.10/api/api-export.rst index 5421c3735..e4702c628 100644 --- a/ja/15.10/api/api-export.rst +++ b/ja/15.10/api/api-export.rst @@ -74,5 +74,7 @@ JSON は ``{"data":[{...},...]}`` の形式で、複数の値を持つフィー - 1 分あたりのリクエスト数の上限を超えた場合。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 表: エラーレスポンス diff --git a/ja/15.10/api/api-health.rst b/ja/15.10/api/api-health.rst index bcd30ca62..e82036b98 100644 --- a/ja/15.10/api/api-health.rst +++ b/ja/15.10/api/api-health.rst @@ -104,6 +104,8 @@ curl コマンドでのリクエスト例: - 説明 * - 200 OK - クラスターが ``GREEN`` / ``YELLOW`` で到達可能な場合。成功エンベロープに ``engine`` が含まれます。 + * - 400 Bad Request + - デコードできないリクエストパラメーター（ ``?q=%ff`` など）が指定された場合。 ``error.code`` は ``invalid_request`` です。 * - 405 Method Not Allowed - HTTP メソッドが許可されていない場合。 * - 503 Service Unavailable diff --git a/ja/15.10/api/api-label.rst b/ja/15.10/api/api-label.rst index 1b091673b..216383f9b 100644 --- a/ja/15.10/api/api-label.rst +++ b/ja/15.10/api/api-label.rst @@ -90,6 +90,8 @@ curl コマンドでのリクエスト例: * - ステータスコード - 説明 + * - 400 Bad Request + - デコードできないリクエストパラメーター（ ``?q=%ff`` など）が指定された場合。 ``error.code`` は ``invalid_request`` です。 * - 401 Unauthorized - 認証が必要な場合（ログイン必須設定が有効で匿名の呼び出し元、または未登録・期限切れのアクセストークンを付けた場合）。 ``error.code`` は ``auth_required`` です。 * - 405 Method Not Allowed diff --git a/ja/15.10/api/api-related.rst b/ja/15.10/api/api-related.rst index 5934f95a0..e5afe6a65 100644 --- a/ja/15.10/api/api-related.rst +++ b/ja/15.10/api/api-related.rst @@ -78,6 +78,8 @@ curlコマンドでのリクエスト例: * - ステータスコード - 説明 + * - 400 Bad Request + - デコードできないリクエストパラメーター（ ``?q=%ff`` など）が指定された場合。 ``error.code`` は ``invalid_request`` です。 * - 401 Unauthorized - 認証が必要な場合（ログイン必須設定が有効で匿名の呼び出し元）。 ``error.code`` は ``auth_required`` です。 * - 405 Method Not Allowed @@ -152,6 +154,8 @@ curlコマンドでのリクエスト例: * - ステータスコード - 説明 + * - 400 Bad Request + - デコードできないリクエストパラメーター（ ``?q=%ff`` など）が指定された場合。 ``error.code`` は ``invalid_request`` です。 * - 401 Unauthorized - 認証が必要な場合（ログイン必須設定が有効で匿名の呼び出し元）。 ``error.code`` は ``auth_required`` です。 * - 405 Method Not Allowed diff --git a/ja/15.10/api/api-search-history.rst b/ja/15.10/api/api-search-history.rst index 8392bb956..3b85d58ad 100644 --- a/ja/15.10/api/api-search-history.rst +++ b/ja/15.10/api/api-search-history.rst @@ -94,6 +94,8 @@ HTTPメソッド GET - HTTP メソッドが許可されていない場合。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 表: エラーレスポンス diff --git a/ja/15.10/api/api-search.rst b/ja/15.10/api/api-search.rst index 5e8038eec..230b2e9fc 100644 --- a/ja/15.10/api/api-search.rst +++ b/ja/15.10/api/api-search.rst @@ -291,6 +291,8 @@ HTTPメソッド GET - HTTP メソッドが許可されていない場合。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 表: エラーレスポンス diff --git a/ja/15.10/api/api-suggest.rst b/ja/15.10/api/api-suggest.rst index 4e459e92e..5a631201e 100644 --- a/ja/15.10/api/api-suggest.rst +++ b/ja/15.10/api/api-suggest.rst @@ -127,3 +127,5 @@ curlコマンドでのリクエスト例: - サポートされていない HTTP メソッドが指定された場合。 ``Allow`` ヘッダーに ``GET`` が示されます。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 diff --git a/ja/15.10/api/api-tag.rst b/ja/15.10/api/api-tag.rst index 6258007ce..adc1a3ee0 100644 --- a/ja/15.10/api/api-tag.rst +++ b/ja/15.10/api/api-tag.rst @@ -319,6 +319,8 @@ HTTPメソッド DELETE - サポートされていない ``Content-Type`` の場合。 * - 500 Internal Server Error - サーバー内部エラーが発生した場合。 + * - 503 Service Unavailable + - 検索エンジンがリクエストを処理できなかった場合（到達できない、または処理能力の不足で拒否された場合）。 ``error.code`` は ``service_unavailable`` で、待つべき秒数（ ``5`` ）を示す ``Retry-After`` ヘッダーが付きます。リクエストに問題はないため、しばらく待って再試行してください。 表: エラーレスポンス diff --git a/ja/15.10/api/api-uiconfig.rst b/ja/15.10/api/api-uiconfig.rst index ce964415e..577726747 100644 --- a/ja/15.10/api/api-uiconfig.rst +++ b/ja/15.10/api/api-uiconfig.rst @@ -406,6 +406,8 @@ filetype_options * - ステータスコード - 説明 + * - 400 Bad Request + - デコードできないリクエストパラメーター（ ``?q=%ff`` など）が指定された場合。 ``error.code`` は ``invalid_request`` です。 * - 405 Method Not Allowed - サポートされていない HTTP メソッドが指定された場合。 * - 500 Internal Server Error diff --git a/ja/15.10/install/upgrade.rst b/ja/15.10/install/upgrade.rst index 0f97c502f..0629a3b2c 100644 --- a/ja/15.10/install/upgrade.rst +++ b/ja/15.10/install/upgrade.rst @@ -1205,6 +1205,18 @@ API が拒否するようになったリクエスト 一致しない - 保存され、そのパスワードでログインできます - ``400`` + * - ``GET /api/admin/log/file/{id}`` で、ログファイルとして許可されない名前（ ``.log`` ・ ``.log.gz`` で終わらない名前など）や、ログのディレクトリにないファイルを指定する + - 許可されない名前は ``200`` で空のレスポンス + - ``400`` + * - 管理 API の ``mapping`` 辞書に、 ``output`` を省略した項目を登録・更新する + - ``200`` （ ``id`` は ``0`` ）。何も保存されません + - ``400`` + * - ストレージにアクセスできないときの ``GET /api/admin/storage/list`` （ストレージクライアントのプラグインが導入されていない場合を含む） + - ``200`` （ ``status`` は ``0`` ）。空の一覧 + - ``400`` 。 ``message`` に原因が入り、プラグインがない場合は導入するプラグインが示されます + * - ログインフォーム（ ``POST /login/login`` ）で、同じ IP アドレスから、または同じ IP アドレスから同じユーザーに対して、ログインを短時間に繰り返し失敗する + - 制限なし + - IP 単位または IP とユーザーの組ごとの上限（ ``theme.api.login.rate.limit.per.ip.per.minute`` ・ ``theme.api.login.rate.limit.per.user.per.minute`` ）を超えると、その IP アドレス（ユーザー単位の上限の場合は、その IP アドレスからのそのユーザー）からのログインは、正しい資格情報でも ``theme.api.login.lockout.seconds`` 秒間拒否されます。応答は資格情報が誤っているときと同じログインエラーです。上限とロックアウトは ``/api/v2/auth/login`` と共有されます（ :doc:`../api/api-auth` を参照） ``/api/v2/documents/all`` の各行から ``score`` がなくなりました。15.8 では各文書に検索スコアが付いていましたが、 15.10 は全件の取得を point in time と ``search_after`` で行うため、スコアは付きません。旧 API プラグインの @@ -1216,6 +1228,15 @@ API が拒否するようになったリクエスト 届かず、15.8 でも 15.10 でも「ファイルが必要です」という検証エラーになります。 ``PUT`` のエンドポイントは\ 残っていますが、アップロードには ``POST`` を使ってください。 +次の変更は、リクエストの拒否ではありませんが、API や管理画面を使うスクリプトやクライアントに影響する場合があります。 + +- 管理 API の ``webauth`` ・ ``fileauth`` の取得（ ``/api/admin/webauth/settings`` ・ ``/api/admin/webauth/setting/{id}`` と、 ``fileauth`` の同じエンドポイント）は、保存されているパスワードを返さなくなりました。 ``PUT`` でパスワードを省略するか空にすると、保存されているパスワードが残ります。空でないパスワードを送ると置き換えられます。 +- ログインしているユーザーは、リクエストに含まれる ``userCode`` パラメーターや Cookie ではなく、セッションで識別されます（お気に入りの API など）。匿名のユーザーは従来どおりパラメーターと Cookie を使います。 +- 管理画面の「検索リスト」と「クロール情報」の「すべて削除」には、編集ロール（ ``admin-searchlist`` ・ ``admin-crawlinginfo`` ）が必要です。表示ロール（ ``-view`` が付くロール）だけを持つユーザーのリクエストは拒否されます。 +- ``fess.xml`` の ``roleQueryHelper`` で ``parameterKey`` ・ ``headerKey`` ・ ``cookieKey`` を有効にしたのに ``cipher`` を設定せず、値の暗号化のフラグ（ ``encryptedParameterValue`` ・ ``encryptedHeaderValue`` ・ ``encryptedCookieValue`` ）が既定値の ``true`` のままの場合、15.8 は値を暗号化されていないロール情報として読んでいました。15.10 はその値を無視し、警告を一度ログに出力します。暗号化した値を使うなら ``cipher`` を設定し、暗号化していない値を受け取る意図なら、フラグを ``false`` にしてください。 +- Content-Type に、JVM が認識しない文字コード（ ``charset=nope`` など）を指定したリクエストは、文字コードの指定がないものとして処理されます。以前は ``/api/v2/search`` が ``500`` （ ``internal_error`` ）を返していました。 +- ``kuromoji`` ・ ``mapping`` ・ ``stemmeroverride`` ・ ``synonym`` の辞書をアップロード・ダウンロードする管理 API が失敗したときのメッセージは、その辞書の種類を示すようになりました。15.8 では、どの辞書でも「protwords ファイル」と表示されていました。 + ``search_engine.type`` の ``cloud`` は非推奨 -------------------------------------------- diff --git a/ko/15.10/api/admin/api-admin-dict.rst b/ko/15.10/api/admin/api-admin-dict.rst index 0b5c81990..dd4c60c55 100644 --- a/ko/15.10/api/admin/api-admin-dict.rst +++ b/ko/15.10/api/admin/api-admin-dict.rst @@ -422,7 +422,7 @@ Dict API는 |Fess| 의 사전을 관리하기 위한 API입니다. - ``token`` (필수)、 ``segmentation`` (필수)、 ``reading`` (필수)、 ``pos`` (필수) - ``kuromojiFile`` * - ``mapping`` - - ``inputs`` (필수)、 ``output`` + - ``inputs`` (필수)、 ``output`` (필수) - ``charMappingFile`` * - ``protwords`` - ``input`` (필수) diff --git a/ko/15.10/api/admin/api-admin-log.rst b/ko/15.10/api/admin/api-admin-log.rst index 2aea3bbaf..c8273feb6 100644 --- a/ko/15.10/api/admin/api-admin-log.rst +++ b/ko/15.10/api/admin/api-admin-log.rst @@ -109,7 +109,11 @@ Log API는 |Fess| 의 로그 파일을 참조·다운로드하기 위한 API입 ``{id}`` 에는 목록 조회에서 반환된 ``id`` (파일명을 Base64 URL 인코딩한 값)를 그대로 지정합니다. 응답은 ``application/octet-stream`` 의 스트림으로 반환됩니다. 보안상의 이유로, ``.log`` 또는 ``.log.gz`` 로 끝나는 이름만 대상이 되며, ``..`` 등의 경로 조작을 포함하는 이름은 허용되지 않습니다. -존재하지 않는 파일명이나 로그 파일로 허용되지 않는 이름을 지정한 경우에는 빈 응답이 반환됩니다. +존재하지 않는 파일명, 로그 파일로 허용되지 않는 이름, 또는 Base64 로 올바르지 않은 ``id`` 를 지정한 경우에는 검증 오류(HTTP ``400``, 응답 본문의 ``status`` 는 ``1``)가 반환됩니다. + +.. note:: + + ``id`` 는 URL-safe Base64(``-`` 와 ``_`` 사용)입니다. 표준 알파벳(``+`` 와 ``/``)의 ``id`` 도 받아들이지만, URL 에 포함할 때의 모호함을 피하기 위해 목록 조회에서 반환된 ``id`` 를 그대로 사용하십시오. 요청 ---------- @@ -123,6 +127,8 @@ Log API는 |Fess| 의 로그 파일을 참조·다운로드하기 위한 API입 로그 파일의 바이너리 스트림(``Content-Type: application/octet-stream``). +지정한 이름의 로그 파일을 찾을 수 없는 경우에는 HTTP ``400`` 이며 응답 본문의 ``status`` 가 ``1`` 인 오류 응답이 반환됩니다(빈 응답이 아닙니다). + 사용 예 ======= diff --git a/ko/15.10/api/admin/api-admin-storage.rst b/ko/15.10/api/admin/api-admin-storage.rst index 51f49221e..a89c4f6f2 100644 --- a/ko/15.10/api/admin/api-admin-storage.rst +++ b/ko/15.10/api/admin/api-admin-storage.rst @@ -10,7 +10,7 @@ Storage API는 |Fess| 의 오브젝트 스토리지를 관리하기 위한 API .. note:: - 이 API 는 스토리지 클라이언트를 제공하는 플러그인이 설치되어 있어야 사용할 수 있습니다. Amazon S3 와 S3 호환 스토리지는 ``fess-storage-s3`` , Google Cloud Storage 는 ``fess-storage-gcs`` 입니다. 플러그인은 배포본에 포함되어 있지 않습니다. 설치되어 있지 않으면 설정된 ``storage.type`` 에 대응하는 클라이언트가 없어 요청이 실패합니다. 관리 화면의 「시스템 > 플러그인」 페이지 또는 ``bin/fess-setup install plugin fess-storage-s3`` (GCS 의 경우 ``fess-storage-gcs`` )로 설치하십시오. + 이 API 는 스토리지 클라이언트를 제공하는 플러그인이 설치되어 있어야 사용할 수 있습니다. Amazon S3 와 S3 호환 스토리지는 ``fess-storage-s3`` , Google Cloud Storage 는 ``fess-storage-gcs`` 입니다. 플러그인은 배포본에 포함되어 있지 않습니다. 설치되어 있지 않으면 설정된 ``storage.type`` 에 대응하는 클라이언트가 없어 요청이 실패합니다. 예를 들어 ``GET /api/admin/storage/list`` 는 빈 목록이 아니라 HTTP ``400`` (``status`` 는 ``1``)의 오류를 반환하며, ``message`` 에는 ("Storage Access Error" 접두어 뒤에) ``No storage client is registered as ...`` 가 포함되며, 설치해야 할 플러그인을 알려 줍니다. 관리 화면의 「시스템 > 플러그인」 페이지 또는 ``bin/fess-setup install plugin fess-storage-s3`` (GCS 의 경우 ``fess-storage-gcs`` )로 설치하십시오. 기본 URL ============ @@ -228,7 +228,7 @@ Storage API를 포함한 Admin API의 모든 엔드포인트에는 액세스 토 * - 엔드포인트 - 오류가 발생하는 주요 케이스 * - 파일·디렉터리 목록 조회 - - 조회 건수가 상한을 초과한 경우 + - 조회 건수가 상한을 초과한 경우, 또는 스토리지에 접근할 수 없는 경우(스토리지 클라이언트 플러그인이 설치되어 있지 않은 경우 포함) * - 파일 다운로드 - ``id`` 가 잘못된 경우, 또는 다운로드에 실패한 경우 * - 파일 삭제 diff --git a/ko/15.10/api/api-auth.rst b/ko/15.10/api/api-auth.rst index 04d6d0b16..22513fcb1 100644 --- a/ko/15.10/api/api-auth.rst +++ b/ko/15.10/api/api-auth.rst @@ -145,6 +145,8 @@ HTTP 메서드 GET * - 상태 코드 - 설명 + * - 400 Bad Request + - 디코딩할 수 없는 요청 파라미터 (예: ``?q=%ff``)가 지정된 경우. ``error.code`` 는 ``invalid_request`` 입니다. * - 405 Method Not Allowed - 지원되지 않는 HTTP 메서드가 지정된 경우. * - 500 Internal Server Error @@ -162,7 +164,7 @@ HTTP 메서드 POST ================== ==================================================== 사용자 이름과 비밀번호로 로그인합니다. -로그인 성공 시에는 서블릿의 세션 ID 가 교체되고, 새 CSRF 토큰이 발급되며, 호출 원 IP 와 대상 사용자의 속도 제한 버킷이 초기화됩니다. +로그인 성공 시에는 서블릿의 세션 ID 가 교체되고, 새 CSRF 토큰이 발급됩니다. 또한 같은 호출 원 IP 와 사용자 이름의 조합으로 그때까지 실패한 시도의 기록 (사용자 단위 버킷) 이 초기화됩니다. IP 단위 버킷은 같은 IP 에서 다른 사용자를 대상으로 한 시도도 세고 있으므로 초기화되지 않으며, 이 시도가 소비한 1회분만 반환됩니다. 속도 제한은 호출 원 IP 단위와 사용자 단위의 2계통으로 적용됩니다. IP 단위의 상한을 초과한 경우 ``429 Too Many Requests`` 를 반환하고 ``Retry-After`` 헤더 (초) 가 부여됩니다. 사용자 단위의 상한을 초과한 경우 카운터 상태가 외부에서 추측되지 않도록, 자격증명이 올바르지 않은 경우와 동일한 ``401 Unauthorized`` 가 ( ``Retry-After`` 헤더 없이) 반환됩니다. @@ -183,10 +185,14 @@ HTTP 메서드 POST 로그인 및 비밀번호 변경의 속도 제한은 다음 프로퍼티로 설정할 수 있습니다 (괄호 안은 기본값). - - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): IP 주소 단위의 분당 최대 시도 횟수. ``/auth/login`` 에만 적용됩니다. - - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): 사용자 단위의 분당 최대 시도 횟수. ``/auth/login`` 과 ``/auth/password`` 양쪽에 적용됩니다. + - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): IP 주소 단위의 분당 최대 시도 횟수. ``/auth/login`` 과 로그인 폼의 ``POST /login/login`` 양쪽에 적용되며, 두 엔드포인트는 같은 버킷을 공유합니다. + - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): 사용자 단위의 분당 최대 시도 횟수. ``/auth/login`` 과 ``POST /login/login`` (호출 원 IP 와 사용자 이름의 조합마다 같은 버킷을 공유), 그리고 ``/auth/password`` 에 적용됩니다. - ``theme.api.login.lockout.seconds`` (``900``): 상한 초과 후의 잠금 시간 (초). ``Retry-After`` 헤더의 값으로 반환됩니다. + 로그인 폼 (``POST /login/login``) 은 ``/auth/login`` 과 같은 버킷과 잠금을 공유하므로, 폼에서의 실패도 ``/auth/login`` 의 상한에 포함되며 그 반대도 마찬가지입니다. 폼에서 상한을 초과한 경우에는 ``429`` 가 아니라 일반적인 로그인 오류로 처리됩니다. + + ``rate.limit.trusted.proxies`` (기본값 ``127.0.0.1,::1``) 에 포함되지 않은 리버스 프록시 뒤에서는 모든 클라이언트가 하나의 IP 주소 (프록시의 주소) 로 취급됩니다. 그 때문에 로그인 실패가 계속되면 잠금 시간 동안 모든 사용자가 로그인할 수 없게 될 수 있습니다. 프록시의 주소를 ``rate.limit.trusted.proxies`` 에 추가하여 ``X-Forwarded-For`` 에서 실제 클라이언트 IP 가 사용되도록 하십시오. + 요청 본문 (LoginRequest) ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -284,12 +290,16 @@ Content-Type 은 ``application/json`` (문자 인코딩 UTF-8) 입니다. 요청 - 요청이 잘못된 경우 (과도한 요청 본문이나 비지원 ``Content-Type`` 포함). * - 401 Unauthorized - 자격증명이 올바르지 않은 경우. + * - 403 Forbidden + - 요청이 크로스 사이트로 차단된 경우 (``Origin`` 또는 ``Referer`` 헤더가 허용되지 않는 오리진을 나타냄). 상태를 변경하는 모든 요청이 거치는 기본 검사이며, 로그인에 필요하지 않은 CSRF 토큰과는 별개입니다. * - 405 Method Not Allowed - 지원되지 않는 HTTP 메서드가 지정된 경우. * - 429 Too Many Requests - 속도 제한을 초과한 경우. ``Retry-After`` 헤더에 대기해야 할 초 단위 시간이 표시됩니다. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. 로그아웃 ======== @@ -344,6 +354,8 @@ HTTP 메서드 POST * - 상태 코드 - 설명 + * - 400 Bad Request + - 디코딩할 수 없는 요청 파라미터 (예: ``?q=%ff``)가 지정된 경우. ``error.code`` 는 ``invalid_request`` 입니다. * - 403 Forbidden - CSRF 토큰이 누락·만료된 경우. * - 405 Method Not Allowed @@ -456,3 +468,5 @@ Content-Type 은 ``application/json`` (문자 인코딩 UTF-8) 입니다. 요청 - 속도 제한을 초과한 경우. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. diff --git a/ko/15.10/api/api-cache.rst b/ko/15.10/api/api-cache.rst index 7ed952f76..4c8f179bf 100644 --- a/ko/15.10/api/api-cache.rst +++ b/ko/15.10/api/api-cache.rst @@ -96,5 +96,7 @@ HTTP 메서드 GET - HTTP 메서드가 허용되지 않는 경우. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. 표: 오류 응답 diff --git a/ko/15.10/api/api-click.rst b/ko/15.10/api/api-click.rst index 52c0918f7..d1d3777fd 100644 --- a/ko/15.10/api/api-click.rst +++ b/ko/15.10/api/api-click.rst @@ -108,5 +108,7 @@ HTTP 메서드 POST - ``Content-Type`` 이 ``application/json`` 이 아닌 경우 (UTF-8 이 필요합니다). * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. 표: 오류 응답 diff --git a/ko/15.10/api/api-export.rst b/ko/15.10/api/api-export.rst index d9100b406..eb75a5586 100644 --- a/ko/15.10/api/api-export.rst +++ b/ko/15.10/api/api-export.rst @@ -74,5 +74,7 @@ JSON 은 ``{"data":[{...},...]}`` 형식이며, 여러 값을 가진 필드는 - 1분당 요청 수 상한을 초과한 경우. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. 표: 오류 응답 diff --git a/ko/15.10/api/api-health.rst b/ko/15.10/api/api-health.rst index 5c04a4ad8..2175bd185 100644 --- a/ko/15.10/api/api-health.rst +++ b/ko/15.10/api/api-health.rst @@ -104,6 +104,8 @@ curl 명령으로 요청 예: - 설명 * - 200 OK - 클러스터가 ``GREEN`` / ``YELLOW`` 이며 도달 가능한 경우. 성공 엔벨로프에 ``engine`` 이 포함됩니다. + * - 400 Bad Request + - 디코딩할 수 없는 요청 파라미터 (예: ``?q=%ff``)가 지정된 경우. ``error.code`` 는 ``invalid_request`` 입니다. * - 405 Method Not Allowed - HTTP 메서드가 허용되지 않는 경우. * - 503 Service Unavailable diff --git a/ko/15.10/api/api-label.rst b/ko/15.10/api/api-label.rst index 7ab87bcc2..64ca16ad8 100644 --- a/ko/15.10/api/api-label.rst +++ b/ko/15.10/api/api-label.rst @@ -90,6 +90,8 @@ curl 명령으로 요청 예: * - 상태 코드 - 설명 + * - 400 Bad Request + - 디코딩할 수 없는 요청 파라미터 (예: ``?q=%ff``)가 지정된 경우. ``error.code`` 는 ``invalid_request`` 입니다. * - 401 Unauthorized - 인증이 필요한 경우 (로그인 필수 설정이 활성화되어 있고 익명 호출자이거나, 등록되지 않았거나 만료된 액세스 토큰이 포함된 요청). ``error.code`` 는 ``auth_required`` 입니다. * - 405 Method Not Allowed diff --git a/ko/15.10/api/api-related.rst b/ko/15.10/api/api-related.rst index 3846e0f74..1617653a9 100644 --- a/ko/15.10/api/api-related.rst +++ b/ko/15.10/api/api-related.rst @@ -78,6 +78,8 @@ curl 명령으로 요청 예: * - 상태 코드 - 설명 + * - 400 Bad Request + - 디코딩할 수 없는 요청 파라미터 (예: ``?q=%ff``)가 지정된 경우. ``error.code`` 는 ``invalid_request`` 입니다. * - 401 Unauthorized - 인증이 필요한 경우 (로그인 필수 설정이 활성화되어 있고 익명 호출자). ``error.code`` 는 ``auth_required`` 입니다. * - 405 Method Not Allowed @@ -152,6 +154,8 @@ curl 명령으로 요청 예: * - 상태 코드 - 설명 + * - 400 Bad Request + - 디코딩할 수 없는 요청 파라미터 (예: ``?q=%ff``)가 지정된 경우. ``error.code`` 는 ``invalid_request`` 입니다. * - 401 Unauthorized - 인증이 필요한 경우 (로그인 필수 설정이 활성화되어 있고 익명 호출자). ``error.code`` 는 ``auth_required`` 입니다. * - 405 Method Not Allowed diff --git a/ko/15.10/api/api-search-history.rst b/ko/15.10/api/api-search-history.rst index 8a2f4535b..624744b6c 100644 --- a/ko/15.10/api/api-search-history.rst +++ b/ko/15.10/api/api-search-history.rst @@ -95,6 +95,8 @@ HTTP 메서드 GET - HTTP 메서드가 허용되지 않는 경우. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. 표: 오류 응답 diff --git a/ko/15.10/api/api-search.rst b/ko/15.10/api/api-search.rst index 4a6f7736f..0d51e538c 100644 --- a/ko/15.10/api/api-search.rst +++ b/ko/15.10/api/api-search.rst @@ -291,6 +291,8 @@ HTTP 메서드 GET - HTTP 메서드가 허용되지 않는 경우. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. 표: 오류 응답 diff --git a/ko/15.10/api/api-suggest.rst b/ko/15.10/api/api-suggest.rst index 35c4d5b55..bab313126 100644 --- a/ko/15.10/api/api-suggest.rst +++ b/ko/15.10/api/api-suggest.rst @@ -127,3 +127,5 @@ curl 명령으로 요청 예: - 지원되지 않는 HTTP 메서드가 지정된 경우. ``Allow`` 헤더에 ``GET`` 이 표시됩니다. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. diff --git a/ko/15.10/api/api-tag.rst b/ko/15.10/api/api-tag.rst index 550bec94f..b8dbb3221 100644 --- a/ko/15.10/api/api-tag.rst +++ b/ko/15.10/api/api-tag.rst @@ -320,6 +320,8 @@ HTTP 메서드 DELETE - 지원되지 않는 ``Content-Type`` 인 경우. * - 500 Internal Server Error - 서버 내부 오류가 발생한 경우. + * - 503 Service Unavailable + - 검색 엔진이 요청을 처리하지 못한 경우 (연결할 수 없거나 처리 능력 부족으로 요청을 거부한 경우). ``error.code`` 는 ``service_unavailable`` 이며, 기다려야 할 초 수 (``5`` ) 를 나타내는 ``Retry-After`` 헤더가 붙습니다. 요청 자체에는 문제가 없으므로 잠시 후 다시 시도하십시오. 표: 오류 응답 diff --git a/ko/15.10/api/api-uiconfig.rst b/ko/15.10/api/api-uiconfig.rst index d86c64e16..695c1317b 100644 --- a/ko/15.10/api/api-uiconfig.rst +++ b/ko/15.10/api/api-uiconfig.rst @@ -406,6 +406,8 @@ filetype_options * - 상태 코드 - 설명 + * - 400 Bad Request + - 디코딩할 수 없는 요청 파라미터 (예: ``?q=%ff``)가 지정된 경우. ``error.code`` 는 ``invalid_request`` 입니다. * - 405 Method Not Allowed - 지원되지 않는 HTTP 메서드가 지정된 경우. * - 500 Internal Server Error diff --git a/ko/15.10/install/upgrade.rst b/ko/15.10/install/upgrade.rst index a6cbd3562..34522e146 100644 --- a/ko/15.10/install/upgrade.rst +++ b/ko/15.10/install/upgrade.rst @@ -1200,6 +1200,18 @@ API 가 거부하게 된 요청 * - 관리 API 로 사용자에게 비밀번호 정책(``password.min.length`` 의 기본값 ``8`` 등)에 어긋나는 비밀번호를 설정, 생성 시 비밀번호를 생략, 또는 ``password`` 와 일치하지 않는 ``confirm_password`` 를 전송 - 저장되며, 그 비밀번호로 로그인할 수 있습니다 - ``400`` + * - ``GET /api/admin/log/file/{id}`` 에 로그 파일로 허용되지 않는 이름(``.log`` 또는 ``.log.gz`` 로 끝나지 않는 이름 등)이나 로그 디렉터리에 없는 파일을 지정 + - 허용되지 않는 이름은 ``200`` 으로 빈 응답 + - ``400`` + * - 관리 API 로 ``mapping`` 사전에 ``output`` 을 생략한 항목을 등록·갱신 + - ``200`` (``id`` 는 ``0``). 아무것도 저장되지 않음 + - ``400`` + * - 스토리지에 접근할 수 없을 때의 ``GET /api/admin/storage/list`` (스토리지 클라이언트 플러그인이 설치되어 있지 않은 경우 포함) + - ``200`` (``status`` 는 ``0``). 빈 목록 + - ``400``. ``message`` 에 원인이 담기며, 플러그인이 없는 경우에는 설치할 플러그인이 표시됨 + * - 로그인 폼(``POST /login/login``)에서 같은 IP 주소로부터, 또는 같은 IP 주소에서 같은 사용자에 대해 짧은 시간에 로그인 실패를 반복 + - 제한 없음 + - IP 단위 또는 IP 와 사용자의 조합 단위 상한(``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``)을 초과하면, 해당 IP 주소(사용자 단위 상한의 경우 해당 IP 주소로부터의 해당 사용자)로부터의 로그인은 올바른 자격증명이라도 ``theme.api.login.lockout.seconds`` 초 동안 거부됨. 응답은 자격증명이 잘못되었을 때와 같은 로그인 오류. 상한과 잠금은 ``/api/v2/auth/login`` 과 공유됨(:doc:`../api/api-auth` 참조) ``/api/v2/documents/all`` 의 각 행에서 ``score`` 가 없어졌습니다. 15.8 까지는 각 문서에 검색 점수가 붙었지만, 15.10 는 전체 결과를 point in time 과 ``search_after`` 로 가져오므로 점수가 붙지 않습니다. 구 API 플러그인의 ``/json?type=scroll`` 과 ``/api/v1/documents/all`` 도 @@ -1209,6 +1221,15 @@ time 과 ``search_after`` 로 가져오므로 점수가 붙지 않습니다. 구 안내했지만, ``multipart/form-data`` 의 ``PUT`` 으로는 파일이 전달되지 않아 15.8 에서도 15.10 에서도 파일이 필요하다는 검증 오류가 됩니다. ``PUT`` 엔드포인트는 남아 있지만, 업로드에는 ``POST`` 를 사용하십시오. +다음 변경은 요청 거부는 아니지만, API 나 관리 화면을 사용하는 스크립트와 클라이언트에 영향을 줄 수 있습니다. + +- 관리 API 의 ``webauth`` ·``fileauth`` 조회(``/api/admin/webauth/settings`` ·``/api/admin/webauth/setting/{id}`` 와 ``fileauth`` 의 같은 엔드포인트)는 저장된 비밀번호를 더 이상 반환하지 않습니다. ``PUT`` 에서 비밀번호를 생략하거나 비워 두면 저장된 비밀번호가 유지됩니다. 비어 있지 않은 비밀번호를 보내면 교체됩니다. +- 로그인한 사용자는 요청에 포함된 ``userCode`` 파라미터나 쿠키가 아니라 세션으로 식별됩니다(즐겨찾기 API 등). 익명 사용자는 종전대로 파라미터와 쿠키를 사용합니다. +- 관리 화면의 「검색 목록」과 「크롤 정보」의 「모두 삭제」에는 편집 역할(``admin-searchlist`` ·``admin-crawlinginfo``)이 필요합니다. 조회 역할(``-view`` 가 붙은 역할)만 가진 사용자의 요청은 거부됩니다. +- ``fess.xml`` 의 ``roleQueryHelper`` 에서 ``parameterKey`` ·``headerKey`` ·``cookieKey`` 를 활성화했지만 ``cipher`` 를 설정하지 않았고, 값 암호화 플래그(``encryptedParameterValue`` ·``encryptedHeaderValue`` ·``encryptedCookieValue``)가 기본값 ``true`` 그대로인 경우, 15.8 은 값을 암호화되지 않은 역할 정보로 읽었습니다. 15.10 은 그 값을 무시하고 경고를 한 번 로그에 출력합니다. 값을 암호화하여 사용한다면 ``cipher`` 를 설정하고, 암호화되지 않은 값을 받을 의도라면 플래그를 ``false`` 로 설정하십시오. +- ``Content-Type`` 에 JVM 이 인식하지 못하는 문자 인코딩(``charset=nope`` 등)을 지정한 요청은 문자 인코딩 지정이 없는 것으로 처리됩니다. 이전에는 ``/api/v2/search`` 가 ``500`` (``internal_error``)을 반환했습니다. +- ``kuromoji`` ·``mapping`` ·``stemmeroverride`` ·``synonym`` 사전을 업로드·다운로드하는 관리 API 가 실패했을 때의 메시지에 해당 사전 종류가 표시됩니다. 15.8 에서는 어느 사전이든 「protwords file」이라고 표시되었습니다. + ``search_engine.type`` 의 ``cloud`` 는 사용 중단 예정 ----------------------------------------------------- diff --git a/zh-cn/15.10/api/admin/api-admin-dict.rst b/zh-cn/15.10/api/admin/api-admin-dict.rst index 4e017ac34..7ed2c456e 100644 --- a/zh-cn/15.10/api/admin/api-admin-dict.rst +++ b/zh-cn/15.10/api/admin/api-admin-dict.rst @@ -422,7 +422,7 @@ Dict API是用于管理 |Fess| 词典的API。 - ``token`` （必需）、 ``segmentation`` （必需）、 ``reading`` （必需）、 ``pos`` （必需） - ``kuromojiFile`` * - ``mapping`` - - ``inputs`` （必需）、 ``output`` + - ``inputs`` （必需）、 ``output`` （必需） - ``charMappingFile`` * - ``protwords`` - ``input`` （必需） diff --git a/zh-cn/15.10/api/admin/api-admin-log.rst b/zh-cn/15.10/api/admin/api-admin-log.rst index f3f22ca38..1d6eefb4d 100644 --- a/zh-cn/15.10/api/admin/api-admin-log.rst +++ b/zh-cn/15.10/api/admin/api-admin-log.rst @@ -109,7 +109,11 @@ Log API是用于参阅和下载 |Fess| 日志文件的API。 ``{id}`` 中直接指定列表获取时返回的 ``id``\ （对文件名进行 Base64 URL 编码后的值）。 响应以 ``application/octet-stream`` 流的形式返回。 出于安全考虑，仅接受以 ``.log`` 或 ``.log.gz`` 结尾的文件名，包含 ``..`` 等路径操作的名称将不被接受。 -如果指定了不存在的文件名或不允许作为日志文件的名称，则返回空响应。 +如果指定了不存在的文件名、不允许作为日志文件的名称，或不是有效 Base64 的 ``id``\ ，则返回验证错误（HTTP ``400``\ ，响应体中的 ``status`` 为 ``1``\ ）。 + +.. note:: + + ``id`` 为 URL 安全的 Base64（使用 ``-`` 和 ``_``\ ）。标准字母表（ ``+`` 和 ``/`` ）的 ``id`` 也会被接受，但为避免放入 URL 时产生歧义，请直接使用列表获取时返回的 ``id``\ 。 请求 ---- @@ -123,6 +127,8 @@ Log API是用于参阅和下载 |Fess| 日志文件的API。 日志文件的二进制流（``Content-Type: application/octet-stream``）。 +如果找不到指定名称的日志文件，则返回 HTTP ``400`` 且响应体中 ``status`` 为 ``1`` 的错误响应（而不是空响应）。 + 使用示例 ======== diff --git a/zh-cn/15.10/api/admin/api-admin-storage.rst b/zh-cn/15.10/api/admin/api-admin-storage.rst index 1d10e68e0..52a59091b 100644 --- a/zh-cn/15.10/api/admin/api-admin-storage.rst +++ b/zh-cn/15.10/api/admin/api-admin-storage.rst @@ -10,7 +10,7 @@ Storage API是用于管理 |Fess| 对象存储的API。 .. note:: - 使用此API需要安装提供存储客户端的插件：Amazon S3 及 S3 兼容存储使用 ``fess-storage-s3`` ，Google Cloud Storage 使用 ``fess-storage-gcs`` 。插件未随发行包提供。未安装时，没有与所配置的 ``storage.type`` 对应的客户端，请求会失败。请在管理界面的「系统 > 插件」页面，或使用 ``bin/fess-setup install plugin fess-storage-s3`` （GCS 为 ``fess-storage-gcs`` ）进行安装。 + 使用此API需要安装提供存储客户端的插件：Amazon S3 及 S3 兼容存储使用 ``fess-storage-s3`` ，Google Cloud Storage 使用 ``fess-storage-gcs`` 。插件未随发行包提供。未安装时，没有与所配置的 ``storage.type`` 对应的客户端，请求会失败。例如 ``GET /api/admin/storage/list`` 不会返回空列表，而是返回 HTTP ``400``\ （ ``status`` 为 ``1``\ ）的错误，其 ``message`` 包含 ``No storage client is registered as ...`` （位于“Storage Access Error”前缀之后），并指出需要安装的插件。请在管理界面的「系统 > 插件」页面，或使用 ``bin/fess-setup install plugin fess-storage-s3`` （GCS 为 ``fess-storage-gcs`` ）进行安装。 基础URL ========== @@ -228,7 +228,7 @@ Storage API所属的Admin API全部端点均需要通过访问令牌进行认证 * - 端点 - 发生错误的主要情况 * - 获取文件和目录列表 - - 获取数量超过上限时 + - 获取数量超过上限时，或无法访问存储时（包括未安装存储客户端插件的情况） * - 下载文件 - ``id`` 无效，或下载失败时 * - 删除文件 diff --git a/zh-cn/15.10/api/api-auth.rst b/zh-cn/15.10/api/api-auth.rst index e250b4f27..939155733 100644 --- a/zh-cn/15.10/api/api-auth.rst +++ b/zh-cn/15.10/api/api-auth.rst @@ -145,6 +145,8 @@ HTTP 方法 GET * - 状态码 - 说明 + * - 400 Bad Request + - 指定了无法解码的请求参数（例如 ``?q=%ff`` ）时。 ``error.code`` 为 ``invalid_request`` 。 * - 405 Method Not Allowed - 指定了不支持的 HTTP 方法时。 * - 500 Internal Server Error @@ -162,7 +164,7 @@ HTTP 方法 POST ================== ==================================================== 使用用户名和密码登录。 -登录成功时，Servlet 会话 ID 将轮换，颁发新的 CSRF 令牌，并清除调用方 IP 和目标用户的速率限制桶。 +登录成功时，Servlet 会话 ID 将轮换，颁发新的 CSRF 令牌。同时，同一调用方 IP 与用户名组合此前失败尝试的记录（用户单位的桶）会被清除。IP 单位的桶不会被清除，因为它也统计来自同一 IP 针对其他用户的尝试；仅归还本次尝试所占用的一次配额。 速率限制分为两个维度：调用方 IP 单位和用户单位。超过 IP 单位限制时，返回 ``429 Too Many Requests`` 并附带 ``Retry-After`` 头（单位秒）。超过用户单位限制时，为防止外部推测计数器状态，返回与凭据不正确相同的 ``401 Unauthorized``\ （不附带 ``Retry-After`` 头）。 @@ -183,10 +185,14 @@ HTTP 方法 POST 登录和密码修改的速率限制可通过以下属性进行配置（括号内为默认值）： - - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): 每个 IP 地址每分钟的最大尝试次数。仅适用于 ``/auth/login``\ 。 - - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): 每个用户每分钟的最大尝试次数。适用于 ``/auth/login`` 和 ``/auth/password``\ 。 + - ``theme.api.login.rate.limit.per.ip.per.minute`` (``10``): 每个 IP 地址每分钟的最大尝试次数。同时适用于 ``/auth/login`` 和登录表单 ``POST /login/login``\ ，两者共用同一个桶。 + - ``theme.api.login.rate.limit.per.user.per.minute`` (``5``): 每个用户每分钟的最大尝试次数。适用于 ``/auth/login`` 和 ``POST /login/login``\ （每个调用方 IP 与用户名的组合共用同一个桶）以及 ``/auth/password``\ 。 - ``theme.api.login.lockout.seconds`` (``900``): 超过限制后的锁定时长（秒）。作为 ``Retry-After`` 头的值返回。 + 登录表单（ ``POST /login/login`` ）与 ``/auth/login`` 共用同一组桶和锁定，因此表单上的失败也会计入 ``/auth/login`` 的上限，反之亦然。在表单上超过上限时，不会返回 ``429``\ ，而是作为普通的登录错误处理。 + + 在未列入 ``rate.limit.trusted.proxies``\ （默认值 ``127.0.0.1,::1``\ ）的反向代理之后，所有客户端都会被视为同一个 IP 地址（代理的地址）。因此，持续的登录失败可能导致所有用户在锁定时长内都无法登录。请将代理的地址添加到 ``rate.limit.trusted.proxies``\ ，以便从 ``X-Forwarded-For`` 获取真实的客户端 IP。 + 请求体 (LoginRequest) ~~~~~~~~~~~~~~~~~~~~~ @@ -284,12 +290,16 @@ Content-Type 为 ``application/json``\ （字符集 UTF-8）。请求体大小 - 请求不合法时（包括过大的请求体或不支持的 ``Content-Type``\ ）。 * - 401 Unauthorized - 认证信息不正确时。 + * - 403 Forbidden + - 请求因跨站而被拦截时（ ``Origin`` 或 ``Referer`` 头指向不允许的来源）。这是所有会改变状态的请求都要通过的基本检查，与登录不需要的 CSRF 令牌无关。 * - 405 Method Not Allowed - 指定了不支持的 HTTP 方法时。 * - 429 Too Many Requests - 超过速率限制时。\ ``Retry-After`` 头中会指示需要等待的秒数。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 注销 ==== @@ -344,6 +354,8 @@ HTTP 方法 POST * - 状态码 - 说明 + * - 400 Bad Request + - 指定了无法解码的请求参数（例如 ``?q=%ff`` ）时。 ``error.code`` 为 ``invalid_request`` 。 * - 403 Forbidden - CSRF 令牌缺失或过期时。 * - 405 Method Not Allowed @@ -456,3 +468,5 @@ Content-Type 为 ``application/json``\ （字符集 UTF-8）。请求体大小 - 超过速率限制时。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 diff --git a/zh-cn/15.10/api/api-cache.rst b/zh-cn/15.10/api/api-cache.rst index d1479fcc7..eb64ae97b 100644 --- a/zh-cn/15.10/api/api-cache.rst +++ b/zh-cn/15.10/api/api-cache.rst @@ -96,5 +96,7 @@ HTTP 方法 GET - 不允许使用该 HTTP 方法时。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 表: 错误响应 diff --git a/zh-cn/15.10/api/api-click.rst b/zh-cn/15.10/api/api-click.rst index b53a18b8d..e196908e9 100644 --- a/zh-cn/15.10/api/api-click.rst +++ b/zh-cn/15.10/api/api-click.rst @@ -108,5 +108,7 @@ HTTP 方法 POST - ``Content-Type`` 不是 ``application/json``\ （需使用 UTF-8）。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 表: 错误响应 diff --git a/zh-cn/15.10/api/api-export.rst b/zh-cn/15.10/api/api-export.rst index b52e98439..054f0388b 100644 --- a/zh-cn/15.10/api/api-export.rst +++ b/zh-cn/15.10/api/api-export.rst @@ -74,5 +74,7 @@ JSON 为 ``{"data":[{...},...]}`` 格式，具有多个值的字段保持为数 - 超过每分钟请求数上限时。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 表: 错误响应 diff --git a/zh-cn/15.10/api/api-health.rst b/zh-cn/15.10/api/api-health.rst index 372005690..e68061bdc 100644 --- a/zh-cn/15.10/api/api-health.rst +++ b/zh-cn/15.10/api/api-health.rst @@ -104,6 +104,8 @@ HTTP 方法 GET - 说明 * - 200 OK - 集群为 ``GREEN`` / ``YELLOW`` 且可达时。成功信封中包含 ``engine``\ 。 + * - 400 Bad Request + - 指定了无法解码的请求参数（例如 ``?q=%ff`` ）时。 ``error.code`` 为 ``invalid_request`` 。 * - 405 Method Not Allowed - 不允许使用该 HTTP 方法时。 * - 503 Service Unavailable diff --git a/zh-cn/15.10/api/api-label.rst b/zh-cn/15.10/api/api-label.rst index 0c9fd799f..751cef580 100644 --- a/zh-cn/15.10/api/api-label.rst +++ b/zh-cn/15.10/api/api-label.rst @@ -90,6 +90,8 @@ HTTP 方法 GET * - 状态码 - 说明 + * - 400 Bad Request + - 指定了无法解码的请求参数（例如 ``?q=%ff`` ）时。 ``error.code`` 为 ``invalid_request`` 。 * - 401 Unauthorized - 需要认证时（登录必需设置有效且调用方为匿名，或请求携带了未注册或已过期的访问令牌）。 ``error.code`` 为 ``auth_required``\ 。 * - 405 Method Not Allowed diff --git a/zh-cn/15.10/api/api-related.rst b/zh-cn/15.10/api/api-related.rst index 7788e48f0..3452b80f8 100644 --- a/zh-cn/15.10/api/api-related.rst +++ b/zh-cn/15.10/api/api-related.rst @@ -78,6 +78,8 @@ HTTP 方法 GET * - 状态码 - 说明 + * - 400 Bad Request + - 指定了无法解码的请求参数（例如 ``?q=%ff`` ）时。 ``error.code`` 为 ``invalid_request`` 。 * - 401 Unauthorized - 需要认证时（登录必需设置有效且调用方为匿名）。 ``error.code`` 为 ``auth_required``\ 。 * - 405 Method Not Allowed @@ -152,6 +154,8 @@ HTTP 方法 GET * - 状态码 - 说明 + * - 400 Bad Request + - 指定了无法解码的请求参数（例如 ``?q=%ff`` ）时。 ``error.code`` 为 ``invalid_request`` 。 * - 401 Unauthorized - 需要认证时（登录必需设置有效且调用方为匿名）。 ``error.code`` 为 ``auth_required``\ 。 * - 405 Method Not Allowed diff --git a/zh-cn/15.10/api/api-search-history.rst b/zh-cn/15.10/api/api-search-history.rst index cd7816931..b02c3a42b 100644 --- a/zh-cn/15.10/api/api-search-history.rst +++ b/zh-cn/15.10/api/api-search-history.rst @@ -94,6 +94,8 @@ HTTP 方法 GET - HTTP 方法不被允许时。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 表: 错误响应 diff --git a/zh-cn/15.10/api/api-search.rst b/zh-cn/15.10/api/api-search.rst index 87ffa4643..8518e9d03 100644 --- a/zh-cn/15.10/api/api-search.rst +++ b/zh-cn/15.10/api/api-search.rst @@ -291,6 +291,8 @@ HTTP 方法 GET - 不允许使用该 HTTP 方法时。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 表: 错误响应 diff --git a/zh-cn/15.10/api/api-suggest.rst b/zh-cn/15.10/api/api-suggest.rst index 1b8546b44..cf1960b7f 100644 --- a/zh-cn/15.10/api/api-suggest.rst +++ b/zh-cn/15.10/api/api-suggest.rst @@ -127,3 +127,5 @@ HTTP 方法 GET - 指定了不支持的 HTTP 方法时。\ ``Allow`` 头中会指示 ``GET``\ 。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 diff --git a/zh-cn/15.10/api/api-tag.rst b/zh-cn/15.10/api/api-tag.rst index a193bc662..6f9534de8 100644 --- a/zh-cn/15.10/api/api-tag.rst +++ b/zh-cn/15.10/api/api-tag.rst @@ -319,6 +319,8 @@ HTTP 方法 DELETE - ``Content-Type`` 不受支持时。 * - 500 Internal Server Error - 发生服务器内部错误时。 + * - 503 Service Unavailable + - 搜索引擎无法处理该请求时（无法连接，或因处理能力不足而拒绝了请求）。 ``error.code`` 为 ``service_unavailable`` ，并附带指示等待秒数（ ``5`` ）的 ``Retry-After`` 头。请求本身没有问题，请稍等片刻后重试。 表：错误响应 diff --git a/zh-cn/15.10/api/api-uiconfig.rst b/zh-cn/15.10/api/api-uiconfig.rst index 7d2574fc8..c0ffc58c5 100644 --- a/zh-cn/15.10/api/api-uiconfig.rst +++ b/zh-cn/15.10/api/api-uiconfig.rst @@ -406,6 +406,8 @@ filetype_options * - 状态码 - 说明 + * - 400 Bad Request + - 指定了无法解码的请求参数（例如 ``?q=%ff`` ）时。 ``error.code`` 为 ``invalid_request`` 。 * - 405 Method Not Allowed - 指定了不支持的 HTTP 方法时。 * - 500 Internal Server Error diff --git a/zh-cn/15.10/install/upgrade.rst b/zh-cn/15.10/install/upgrade.rst index 1c4ead23b..be1b8aabe 100644 --- a/zh-cn/15.10/install/upgrade.rst +++ b/zh-cn/15.10/install/upgrade.rst @@ -1133,11 +1133,32 @@ API 现在会拒绝的请求 * - 为管理 API 的用户设置违反密码策略（例如 ``password.min.length`` ，默认值 ``8`` ）的密码；创建时省略密码；发送与 ``password`` 不一致的 ``confirm_password`` - 会被保存，该用户可以用该密码登录 - ``400`` + * - ``GET /api/admin/log/file/{id}`` 指定了不允许作为日志文件的名称（例如不以 ``.log`` 或 ``.log.gz`` 结尾），或不在日志目录中的文件 + - 不允许的名称返回 ``200`` 和空响应 + - ``400`` + * - 通过管理 API 创建或更新省略了 ``output`` 的 ``mapping`` 字典条目 + - ``200`` （ ``id`` 为 ``0`` ）；不保存任何内容 + - ``400`` + * - 无法访问存储时的 ``GET /api/admin/storage/list`` （包括未安装存储客户端插件的情况） + - ``200`` （ ``status`` 为 ``0`` ）和空列表 + - ``400`` 。 ``message`` 给出原因；缺少插件时会指出需要安装的插件 + * - 在登录表单（ ``POST /login/login`` ）上，短时间内从同一 IP 地址，或从同一 IP 地址针对同一用户重复登录失败 + - 无限制 + - 超过按 IP 或按 IP 与用户组合的上限（ ``theme.api.login.rate.limit.per.ip.per.minute`` 、 ``theme.api.login.rate.limit.per.user.per.minute`` ）后，来自该 IP 地址（按用户上限时为来自该 IP 地址的该用户）的登录，即使凭据正确，也会在 ``theme.api.login.lockout.seconds`` 秒内被拒绝。响应与凭据错误时相同，均为登录错误。上限和锁定与 ``/api/v2/auth/login`` 共用（参见 :doc:`../api/api-auth` ） ``/api/v2/documents/all`` 的每一行不再带有 ``score`` 。15.8 及之前，每个文档都带有搜索得分；15.10 使用 point in time 和 ``search_after`` 获取全部结果，因此不会产生得分。旧 API 插件的 ``/json?type=scroll`` 和 ``/api/v1/documents/all`` 也是如此。读取 ``score`` 的脚本需要能够处理该值不存在的情况。 管理 API 的文件上传（6 种字典、 ``badword`` 、 ``elevateword`` 、 ``storage`` ）通过 ``POST`` 接收。15.8 的文档曾介绍使用 ``PUT`` ，但 ``multipart/form-data`` 的 ``PUT`` 不会传送文件，因此在 15.8 和 15.10 中都会因“需要文件”的验证错误而失败。 ``PUT`` 端点仍然保留，但上传请使用 ``POST`` 。 +以下变更不属于请求被拒绝，但可能影响使用 API 或管理界面的脚本和客户端。 + +- 管理 API ``webauth`` 和 ``fileauth`` 的获取请求（ ``/api/admin/webauth/settings`` 、 ``/api/admin/webauth/setting/{id}`` 以及 ``fileauth`` 下相同的端点）不再返回已保存的密码。 ``PUT`` 时省略密码或发送空密码，将保留已保存的密码；发送非空密码则会替换。 +- 已登录的用户由会话识别，而不是由请求携带的 ``userCode`` 参数或 Cookie 识别（例如收藏 API）。匿名用户仍使用参数和 Cookie。 +- 管理界面中「搜索列表」和「爬取信息」的「全部删除」需要编辑角色（ ``admin-searchlist`` 、 ``admin-crawlinginfo`` ）。仅拥有查看角色（带有 ``-view`` 后缀的角色）的用户的请求会被拒绝。 +- 如果在 ``fess.xml`` 的 ``roleQueryHelper`` 中启用了 ``parameterKey`` 、 ``headerKey`` 或 ``cookieKey`` ，却没有设置 ``cipher`` ，并且值加密标志（ ``encryptedParameterValue`` 、 ``encryptedHeaderValue`` 或 ``encryptedCookieValue`` ）仍为默认值 ``true`` ，则 15.8 会把该值当作未加密的角色信息读取。15.10 会忽略该值，并在日志中输出一次警告。如果值已加密，请设置 ``cipher`` ；如果本意是接收未加密的值，请将该标志设为 ``false`` 。 +- ``Content-Type`` 中指定了 JVM 不认识的字符集（例如 ``charset=nope`` ）的请求，将按未指定字符集处理。此前 ``/api/v2/search`` 会返回 ``500`` （ ``internal_error`` ）。 +- 通过管理 API 上传或下载 ``kuromoji`` 、 ``mapping`` 、 ``stemmeroverride`` 、 ``synonym`` 字典失败时，消息现在会指明该字典。在 15.8 中，所有这些字典都显示“protwords file”。 + ``search_engine.type`` 的 ``cloud`` 已弃用 ------------------------------------------ From 6d247daf29812ea6c3d6af12e4dedb3aa1526533 Mon Sep 17 00:00:00 2001 From: Shinsuke Sugaya Date: Sun, 25 Oct 2026 04:35:54 +0900 Subject: [PATCH 2/2] docs(15.10): note the reverse proxy requirement of the login form limit in the upgrade guide Behind a reverse proxy that is not listed in rate.limit.trusted.proxies, all clients share one login rate-limit bucket. Say so in the upgrade table row for the login form limit, in all seven languages. --- de/15.10/install/upgrade.rst | 2 +- en/15.10/install/upgrade.rst | 2 +- es/15.10/install/upgrade.rst | 2 +- fr/15.10/install/upgrade.rst | 2 +- ja/15.10/install/upgrade.rst | 2 +- ko/15.10/install/upgrade.rst | 2 +- zh-cn/15.10/install/upgrade.rst | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/de/15.10/install/upgrade.rst b/de/15.10/install/upgrade.rst index 30546d7bb..57357ca8d 100644 --- a/de/15.10/install/upgrade.rst +++ b/de/15.10/install/upgrade.rst @@ -1278,7 +1278,7 @@ Sie für 15.8 geschrieben haben. Die Admin-API beantwortet eine Ablehnung mit HT - ``400``. ``message`` nennt die Ursache und, falls das Plugin fehlt, das zu installierende Plugin * - Wiederholte fehlgeschlagene Anmeldungen am Anmeldeformular (``POST /login/login``) innerhalb kurzer Zeit von einer IP-Adresse oder für einen Benutzer von einer IP-Adresse - Keine Begrenzung - - Oberhalb des Limits pro Adresse oder pro Benutzer (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``) werden weitere Anmeldungen von dieser Adresse (beim Limit pro Benutzer: für diesen Benutzer von dieser Adresse) ``theme.api.login.lockout.seconds`` Sekunden lang abgelehnt, auch mit korrekten Anmeldedaten. Die Antwort ist dieselbe Anmeldefehlermeldung wie bei falschen Anmeldedaten. Limits und Sperrung werden mit ``/api/v2/auth/login`` geteilt (siehe :doc:`../api/api-auth`) + - Oberhalb des Limits pro Adresse oder pro Benutzer (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``) werden weitere Anmeldungen von dieser Adresse (beim Limit pro Benutzer: für diesen Benutzer von dieser Adresse) ``theme.api.login.lockout.seconds`` Sekunden lang abgelehnt, auch mit korrekten Anmeldedaten. Die Antwort ist dieselbe Anmeldefehlermeldung wie bei falschen Anmeldedaten. Limits und Sperrung werden mit ``/api/v2/auth/login`` geteilt (siehe :doc:`../api/api-auth`) Hinter einem Reverse-Proxy, dessen Adresse nicht in ``rate.limit.trusted.proxies`` steht, werden alle Clients als eine Adresse gezählt, sodass wiederholte Fehlversuche alle Benutzer aussperren können. Tragen Sie die Adresse des Proxys in ``rate.limit.trusted.proxies`` ein (kommt ``X-Forwarded-For`` von einem nicht vertrauenswürdigen Peer, wird einmalig eine Warnung in ``fess.log`` geschrieben). Die Zeilen von ``/api/v2/documents/all`` enthalten kein ``score`` mehr. Bis 15.8 hatte jedes Dokument seinen Suchscore; 15.10 durchläuft das gesamte Ergebnis mit einem Point in Time und ``search_after``, wodurch kein diff --git a/en/15.10/install/upgrade.rst b/en/15.10/install/upgrade.rst index ba462dd2c..33d290fe9 100644 --- a/en/15.10/install/upgrade.rst +++ b/en/15.10/install/upgrade.rst @@ -1223,7 +1223,7 @@ The admin API answers a refusal with HTTP ``400`` and ``status`` ``1`` in the bo - ``400``. ``message`` gives the cause and, when the plugin is missing, names the plugin to install * - Repeated failed logins on the login form (``POST /login/login``) from one IP address, or for one user from one IP address, within a short time - No limit - - Above the per-address or per-user limit (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), further logins from that address (for the per-user limit: for that user from that address) are refused for ``theme.api.login.lockout.seconds`` seconds, even with correct credentials. The response is the same login error as for wrong credentials. The limits and the lockout are shared with ``/api/v2/auth/login`` (see :doc:`../api/api-auth`) + - Above the per-address or per-user limit (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), further logins from that address (for the per-user limit: for that user from that address) are refused for ``theme.api.login.lockout.seconds`` seconds, even with correct credentials. The response is the same login error as for wrong credentials. The limits and the lockout are shared with ``/api/v2/auth/login`` (see :doc:`../api/api-auth`) Behind a reverse proxy whose address is not in ``rate.limit.trusted.proxies``, all clients are counted as one address, so repeated failures can lock every user out. Add the proxy's address to ``rate.limit.trusted.proxies`` (a warning is logged once to ``fess.log`` when ``X-Forwarded-For`` arrives from an untrusted peer). Rows of ``/api/v2/documents/all`` no longer carry ``score``. Up to 15.8 every document had its search score; 15.10 walks the whole result with a point in time and ``search_after``, which gives no score. diff --git a/es/15.10/install/upgrade.rst b/es/15.10/install/upgrade.rst index 9ff3a8670..6702e846f 100644 --- a/es/15.10/install/upgrade.rst +++ b/es/15.10/install/upgrade.rst @@ -1271,7 +1271,7 @@ cuerpo. - ``400``. ``message`` indica la causa y, si falta el plugin, el plugin que debe instalarse * - Inicios de sesión fallidos repetidos en el formulario de inicio de sesión (``POST /login/login``) en poco tiempo, desde una misma dirección IP o para un mismo usuario desde una misma dirección IP - Sin límite - - Al superar el límite por dirección o por usuario (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), los inicios de sesión posteriores desde esa dirección (con el límite por usuario: de ese usuario desde esa dirección) se rechazan durante ``theme.api.login.lockout.seconds`` segundos, incluso con credenciales correctas. La respuesta es el mismo error de inicio de sesión que con credenciales incorrectas. Los límites y el bloqueo se comparten con ``/api/v2/auth/login`` (consulte :doc:`../api/api-auth`) + - Al superar el límite por dirección o por usuario (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), los inicios de sesión posteriores desde esa dirección (con el límite por usuario: de ese usuario desde esa dirección) se rechazan durante ``theme.api.login.lockout.seconds`` segundos, incluso con credenciales correctas. La respuesta es el mismo error de inicio de sesión que con credenciales incorrectas. Los límites y el bloqueo se comparten con ``/api/v2/auth/login`` (consulte :doc:`../api/api-auth`) Detrás de un proxy inverso cuya dirección no figura en ``rate.limit.trusted.proxies``, todos los clientes se cuentan como una sola dirección, por lo que los fallos repetidos pueden bloquear a todos los usuarios. Añada la dirección del proxy a ``rate.limit.trusted.proxies`` (cuando ``X-Forwarded-For`` llega de un par no confiable, se registra una advertencia una sola vez en ``fess.log``). Las filas de ``/api/v2/documents/all`` ya no llevan ``score``. Hasta la 15.8 cada documento tenía su puntuación de búsqueda; la 15.10 recorre todo el resultado con un point in time y ``search_after``, que no diff --git a/fr/15.10/install/upgrade.rst b/fr/15.10/install/upgrade.rst index 9f4144d4d..33f71d050 100644 --- a/fr/15.10/install/upgrade.rst +++ b/fr/15.10/install/upgrade.rst @@ -1283,7 +1283,7 @@ le corps. - ``400``. ``message`` indique la cause et, si le plugin est absent, le plugin à installer * - Connexions échouées répétées sur le formulaire de connexion (``POST /login/login``) en peu de temps, depuis une même adresse IP ou pour un même utilisateur depuis une même adresse IP - Aucune limite - - Au-delà de la limite par adresse ou par utilisateur (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), les connexions suivantes depuis cette adresse (pour la limite par utilisateur : de cet utilisateur depuis cette adresse) sont refusées pendant ``theme.api.login.lockout.seconds`` secondes, même avec des identifiants corrects. La réponse est la même erreur de connexion qu'avec des identifiants erronés. Les limites et le verrouillage sont partagés avec ``/api/v2/auth/login`` (voir :doc:`../api/api-auth`) + - Au-delà de la limite par adresse ou par utilisateur (``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``), les connexions suivantes depuis cette adresse (pour la limite par utilisateur : de cet utilisateur depuis cette adresse) sont refusées pendant ``theme.api.login.lockout.seconds`` secondes, même avec des identifiants corrects. La réponse est la même erreur de connexion qu'avec des identifiants erronés. Les limites et le verrouillage sont partagés avec ``/api/v2/auth/login`` (voir :doc:`../api/api-auth`) Derrière un proxy inverse dont l'adresse ne figure pas dans ``rate.limit.trusted.proxies``, tous les clients sont comptés comme une seule adresse, de sorte que des échecs répétés peuvent verrouiller tous les utilisateurs. Ajoutez l'adresse du proxy à ``rate.limit.trusted.proxies`` (un avertissement est consigné une seule fois dans ``fess.log`` lorsque ``X-Forwarded-For`` provient d'un pair non approuvé). Les lignes de ``/api/v2/documents/all`` ne portent plus ``score``. Jusqu'à la 15.8, chaque document avait son score de recherche ; la 15.10 parcourt tout le résultat avec un point in time et ``search_after``, ce qui diff --git a/ja/15.10/install/upgrade.rst b/ja/15.10/install/upgrade.rst index 0629a3b2c..23fae7dc1 100644 --- a/ja/15.10/install/upgrade.rst +++ b/ja/15.10/install/upgrade.rst @@ -1216,7 +1216,7 @@ API が拒否するようになったリクエスト - ``400`` 。 ``message`` に原因が入り、プラグインがない場合は導入するプラグインが示されます * - ログインフォーム（ ``POST /login/login`` ）で、同じ IP アドレスから、または同じ IP アドレスから同じユーザーに対して、ログインを短時間に繰り返し失敗する - 制限なし - - IP 単位または IP とユーザーの組ごとの上限（ ``theme.api.login.rate.limit.per.ip.per.minute`` ・ ``theme.api.login.rate.limit.per.user.per.minute`` ）を超えると、その IP アドレス（ユーザー単位の上限の場合は、その IP アドレスからのそのユーザー）からのログインは、正しい資格情報でも ``theme.api.login.lockout.seconds`` 秒間拒否されます。応答は資格情報が誤っているときと同じログインエラーです。上限とロックアウトは ``/api/v2/auth/login`` と共有されます（ :doc:`../api/api-auth` を参照） + - IP 単位または IP とユーザーの組ごとの上限（ ``theme.api.login.rate.limit.per.ip.per.minute`` ・ ``theme.api.login.rate.limit.per.user.per.minute`` ）を超えると、その IP アドレス（ユーザー単位の上限の場合は、その IP アドレスからのそのユーザー）からのログインは、正しい資格情報でも ``theme.api.login.lockout.seconds`` 秒間拒否されます。応答は資格情報が誤っているときと同じログインエラーです。上限とロックアウトは ``/api/v2/auth/login`` と共有されます（ :doc:`../api/api-auth` を参照）リバースプロキシの背後で、そのアドレスが ``rate.limit.trusted.proxies`` に含まれていない場合、すべてのクライアントが 1 つのアドレスとして数えられ、失敗が続くと全ユーザーがログインできなくなります。プロキシのアドレスを ``rate.limit.trusted.proxies`` に追加してください（ ``X-Forwarded-For`` が信頼されないピアから届くと、 ``fess.log`` に警告が一度出力されます）。 ``/api/v2/documents/all`` の各行から ``score`` がなくなりました。15.8 では各文書に検索スコアが付いていましたが、 15.10 は全件の取得を point in time と ``search_after`` で行うため、スコアは付きません。旧 API プラグインの diff --git a/ko/15.10/install/upgrade.rst b/ko/15.10/install/upgrade.rst index 34522e146..69b168429 100644 --- a/ko/15.10/install/upgrade.rst +++ b/ko/15.10/install/upgrade.rst @@ -1211,7 +1211,7 @@ API 가 거부하게 된 요청 - ``400``. ``message`` 에 원인이 담기며, 플러그인이 없는 경우에는 설치할 플러그인이 표시됨 * - 로그인 폼(``POST /login/login``)에서 같은 IP 주소로부터, 또는 같은 IP 주소에서 같은 사용자에 대해 짧은 시간에 로그인 실패를 반복 - 제한 없음 - - IP 단위 또는 IP 와 사용자의 조합 단위 상한(``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``)을 초과하면, 해당 IP 주소(사용자 단위 상한의 경우 해당 IP 주소로부터의 해당 사용자)로부터의 로그인은 올바른 자격증명이라도 ``theme.api.login.lockout.seconds`` 초 동안 거부됨. 응답은 자격증명이 잘못되었을 때와 같은 로그인 오류. 상한과 잠금은 ``/api/v2/auth/login`` 과 공유됨(:doc:`../api/api-auth` 참조) + - IP 단위 또는 IP 와 사용자의 조합 단위 상한(``theme.api.login.rate.limit.per.ip.per.minute``, ``theme.api.login.rate.limit.per.user.per.minute``)을 초과하면, 해당 IP 주소(사용자 단위 상한의 경우 해당 IP 주소로부터의 해당 사용자)로부터의 로그인은 올바른 자격증명이라도 ``theme.api.login.lockout.seconds`` 초 동안 거부됨. 응답은 자격증명이 잘못되었을 때와 같은 로그인 오류. 상한과 잠금은 ``/api/v2/auth/login`` 과 공유됨(:doc:`../api/api-auth` 참조) 주소가 ``rate.limit.trusted.proxies`` 에 없는 리버스 프록시 뒤에서는 모든 클라이언트가 하나의 주소로 집계되어, 실패가 반복되면 모든 사용자가 로그인할 수 없게 될 수 있음. 프록시 주소를 ``rate.limit.trusted.proxies`` 에 추가할 것(신뢰되지 않은 피어에서 ``X-Forwarded-For`` 가 도착하면 ``fess.log`` 에 경고가 한 번 출력됨). ``/api/v2/documents/all`` 의 각 행에서 ``score`` 가 없어졌습니다. 15.8 까지는 각 문서에 검색 점수가 붙었지만, 15.10 는 전체 결과를 point in time 과 ``search_after`` 로 가져오므로 점수가 붙지 않습니다. 구 API 플러그인의 ``/json?type=scroll`` 과 ``/api/v1/documents/all`` 도 diff --git a/zh-cn/15.10/install/upgrade.rst b/zh-cn/15.10/install/upgrade.rst index be1b8aabe..b7ea24f3f 100644 --- a/zh-cn/15.10/install/upgrade.rst +++ b/zh-cn/15.10/install/upgrade.rst @@ -1144,7 +1144,7 @@ API 现在会拒绝的请求 - ``400`` 。 ``message`` 给出原因；缺少插件时会指出需要安装的插件 * - 在登录表单（ ``POST /login/login`` ）上，短时间内从同一 IP 地址，或从同一 IP 地址针对同一用户重复登录失败 - 无限制 - - 超过按 IP 或按 IP 与用户组合的上限（ ``theme.api.login.rate.limit.per.ip.per.minute`` 、 ``theme.api.login.rate.limit.per.user.per.minute`` ）后，来自该 IP 地址（按用户上限时为来自该 IP 地址的该用户）的登录，即使凭据正确，也会在 ``theme.api.login.lockout.seconds`` 秒内被拒绝。响应与凭据错误时相同，均为登录错误。上限和锁定与 ``/api/v2/auth/login`` 共用（参见 :doc:`../api/api-auth` ） + - 超过按 IP 或按 IP 与用户组合的上限（ ``theme.api.login.rate.limit.per.ip.per.minute`` 、 ``theme.api.login.rate.limit.per.user.per.minute`` ）后，来自该 IP 地址（按用户上限时为来自该 IP 地址的该用户）的登录，即使凭据正确，也会在 ``theme.api.login.lockout.seconds`` 秒内被拒绝。响应与凭据错误时相同，均为登录错误。上限和锁定与 ``/api/v2/auth/login`` 共用（参见 :doc:`../api/api-auth` ）在地址未列入 ``rate.limit.trusted.proxies`` 的反向代理之后，所有客户端会被算作同一个地址，因此连续失败可能使所有用户无法登录。请将代理的地址添加到 ``rate.limit.trusted.proxies`` （当 ``X-Forwarded-For`` 来自不受信任的对端时， ``fess.log`` 中会输出一次警告）。 ``/api/v2/documents/all`` 的每一行不再带有 ``score`` 。15.8 及之前，每个文档都带有搜索得分；15.10 使用 point in time 和 ``search_after`` 获取全部结果，因此不会产生得分。旧 API 插件的 ``/json?type=scroll`` 和 ``/api/v1/documents/all`` 也是如此。读取 ``score`` 的脚本需要能够处理该值不存在的情况。