document_stream()

Liest einen Byte-Bereich aus einer Dokument-Datei über std.GetDocumentStream. Der Server liest length Bytes ab offset aus der page-ten Datei des Dokuments und liefert sie als Inhalt einer einzelnen Antwort-Datei zurück; der Aufruf konvertiert diese in ein bytes-Objekt.

Diese Methode eignet sich zum Streaming großer Dateien in Chunks, ohne eine Komplett-Kopie über files() herunterladen zu müssen.

1. Signatur

  • Sync

  • Async

ecm.dms.document_stream(
    model: ECMDocumentModel | int,
    object_type_id: int | None = None,
    *,
    offset: int = 0,
    length: int,
    page: int = 1,
) -> bytes
await ecm.dms.document_stream(
    model: ECMDocumentModel | int,
    object_type_id: int | None = None,
    *,
    offset: int = 0,
    length: int,
    page: int = 1,
) -> bytes

2. Parameter

Parameter Typ Standard Beschreibung

model

ECMDocumentModel | int

—

Das Dokument: entweder eine ECMDocumentModel-Instanz (deren system.id verwendet wird) oder eine reine Objekt-ID als int.

object_type_id

int | None

None

Numerische Objekttyp-ID. Wird automatisch aufgelöst, wenn None — entweder aus der Modell-Instanz oder per get_object_type_by_id().

offset

int

0

Null-basierter Byte-Offset, ab dem gelesen wird. Muss kleiner sein als die Dateigröße — sonst liefert der Server ERR_WRONGPARAM.

length

int

—

Anzahl der zu lesenden Bytes. Der Server liefert ggf. weniger Bytes, wenn der angeforderte Bereich über das Dateiende hinausreicht.

page

int

1

Eins-basierter Seitenindex der zu lesenden Dokument-Datei (Standard 1).

3. Rückgabewert

Der angeforderte Byte-Bereich als einzelnes bytes-Objekt. Kann kürzer sein als length, wenn die Datei früher endet. Liefert ein leeres bytes-Objekt, wenn der Server keine Datei zurückgibt.

4. Mögliche Fehlercodes vom Server

Der Server kann folgende Fehler werfen (als ECMException):

  • ERR_WRONGPARAM — offset ist größer als die Dateigröße.

  • ERR_GETOBJECTDEFPARAM — Objekttyp unbekannt.

  • ERR_GETPARAMETER — zu wenige (gültige) Parameter übergeben.

  • ERR_SQLSELECT — Fehler bei DB-Anfragen.

  • ERR_NOTDEFINED_YET — Objekt befindet sich auf einem entfernten Server.

  • ERR_INSOURCE — Datei kann nicht gefunden oder geöffnet werden.

  • ERR_INDESTINATION — Zieldatei kann nicht angelegt werden.

5. Beispiele

5.1. Erste 50 Bytes lesen

  • Sync

  • Async

header = ecm.dms.document_stream(doc, offset=0, length=50)
print(header[:4])  # z. B. file-magic-prüfung
header = await ecm.dms.document_stream(doc, offset=0, length=50)

5.2. Datei in Chunks streamen

  • Sync

  • Async

chunks = []
pos = 0
chunk_size = 64 * 1024  # 64 KiB
while True:
    chunk = ecm.dms.document_stream(doc, offset=pos, length=chunk_size)
    if not chunk:
        break
    chunks.append(chunk)
    pos += len(chunk)
    if len(chunk) < chunk_size:
        break  # End-of-file erreicht
full_content = b"".join(chunks)
chunks = []
pos = 0
chunk_size = 64 * 1024
while True:
    chunk = await ecm.dms.document_stream(doc, offset=pos, length=chunk_size)
    if not chunk:
        break
    chunks.append(chunk)
    pos += len(chunk)
    if len(chunk) < chunk_size:
        break
full_content = b"".join(chunks)

5.3. Per Plain-Integer-ID ohne Typ-Auflösung

Wenn die Objekttyp-ID bereits bekannt ist, kann sie mit übergeben werden, um den zusätzlichen get_object_type_by_id()-Roundtrip zu sparen:

obj_type = ecm.dms.get_object_type_by_id(doc_id)
chunk = ecm.dms.document_stream(doc_id, obj_type, offset=0, length=1024)

6. Vergleich mit files()

Aspekt files() document_stream()

Ergebnistyp

Liste von JobResponseFile

bytes

Übertragung

Komplette Datei(en) am Stück

Konfigurierbarer Byte-Bereich

Mehrere Dateien

Ja (eine pro Seite)

Nein – nur eine Seite pro Aufruf

Streaming-Eignung

Eingeschränkt

Sehr gut – ermöglicht Chunking

Server-Job

std.StoreInCacheById

std.GetDocumentStream

7. Siehe auch

  • files() — Komplette Dateien eines Dokuments laden

  • digest() — Hashwert eines Dokuments abrufen