= get()
:description: Lädt ein einzelnes ECM-Objekt anhand seiner object_id. Erwartet eine typisierte Modellklasse und gibt eine vollständige Instanz zurück oder wirft ECMNotFoundException.
:keywords: get, object_id, ECMNotFoundException, Modellklasse, Instanz, ECMFolderModel, ECMDocumentModel
:page-tags: api, dms

Lädt ein einzelnes Objekt vom Server anhand seiner ID und gibt es als typisierte Modell-Instanz zurück. Wirft `ECMNotFoundException`, wenn kein Objekt mit der angegebenen ID existiert.

Intern stehen zwei Abrufmodi zur Verfügung, die sich in Funktionsumfang und Performance unterscheiden — siehe <<_abrufmodi>>.

== Signatur

[tabs]
====
Sync::
+
[source,python]
----
ecm.dms.get(
    model_class: type[T],
    object_id: int,
    object_type_id: int | None = None,
    *,
    rights: bool = False,
    base_params: bool = False,
    file_properties: bool = False,
    variants: bool = False,
    use_result_list: bool = False,
    fields: list[str | ECMField] | None = None,
) -> T
----

Async::
+
[source,python]
----
await ecm.dms.get(
    model_class: type[T],
    object_id: int,
    object_type_id: int | None = None,
    *,
    rights: bool = False,
    base_params: bool = False,
    file_properties: bool = False,
    variants: bool = False,
    use_result_list: bool = False,
    fields: list[str | ECMField] | None = None,
) -> T
----
====

== Parameter

[cols="1,1,3"]
|===
|Name |Typ |Beschreibung

|`model_class`
|`type[T]`
|Die Modelklasse des gesuchten Objekts. Bestimmt den Objekttyp und die zurückgegebenen Felder.

|`object_id`
|`int`
|Die numerische ID des gesuchten Objekts.

|`object_type_id`
|`int \| None`
|Optionale numerische Objekttyp-ID. Nur im Standard-Modus (`use_result_list=False`) ausgewertet; bei `use_result_list=True` ignoriert. Wird der Parameter weggelassen, ermittelt der Server den Typ automatisch.

|`rights`
|`bool`
|Wenn `True`, werden die Zugriffsrechte des angemeldeten Benutzers abgerufen (befüllt `obj.system.rights`). Standard: `False`.

|`base_params`
|`bool`
|Wenn `True`, werden Verwaltungsparameter abgerufen (befüllt `obj.system.base_params`): Ersteller, Erstelldatum, Eigentümer, letzter Änderer, Änderungsdatum. Standard: `False`.

|`file_properties`
|`bool`
|Wenn `True`, werden Datei-Metadaten abgerufen (befüllt `obj.system.file_properties`). Nur für Dokument-Typen relevant. Standard: `False`.

|`variants`
|`bool`
|Wenn `True`, werden W-Modul-Versionsverzweigungen abgerufen (befüllt `obj.system.variants`). In beiden Modi verfügbar. Standard: `False`.

|`use_result_list`
|`bool`
|Schaltet den Abrufmodus um — siehe <<_abrufmodi>>. Standard: `False`.

|`fields`
|`list[str \| ECMField] \| None`
|Schränkt die zurückgegebenen Felder ein. Nur bei `use_result_list=True` wirksam; bei `use_result_list=False` stillschweigend ignoriert. `None` gibt alle Felder zurück. Standard: `None`.
|===

== Rückgabewert

Eine typisierte Modell-Instanz des angeforderten Objekts.

== Ausnahmen

`ECMNotFoundException`:: Wird geworfen, wenn kein Objekt mit der angegebenen ID auf dem Server existiert.

== Abrufmodi

`get()` unterstützt zwei interne Abrufmethoden, die sich in Umfang und Einschränkungen unterscheiden:

[cols="1,1,1"]
|===
| |`use_result_list=False` (Standard) |`use_result_list=True`

|Server-Job
|`dms.GetObjectDetails`
|`dms.GetResultList` (HOL)

|Performance
|Schneller (direkter ID-Lookup)
|Langsamer (Abfrage + Paging)

|Dokument-Ortsfelder +
(`folder_id`, `register_id`)
|Nicht verfügbar
|Verfügbar

|`variants`
|Verfügbar
|Verfügbar

|`fields`
|Nicht verfügbar (ignoriert)
|Verfügbar

|Objekte ohne Ablageort +
(kein Ordner/Register)
|Abrufbar
|Wirft `ECMNotFoundException`
|===

[NOTE]
====
`use_result_list=True` erfordert, dass das Objekt in der Ablagestruktur abgelegt ist (d.h. einem Ordner oder Register zugeordnet ist). Objekte ohne Ablageort können über `GetResultList` nicht gefunden werden.
====

== Beispiele

=== Einfacher Abruf

[tabs]
====
Sync::
+
[source,python]
----
folder = ecm.dms.get(InvoiceFolder, 12345)
print(folder.Title, folder.Year)
----

Async::
+
[source,python]
----
folder = await ecm.dms.get(InvoiceFolder, 12345)
print(folder.Title, folder.Year)
----
====

=== Mit Fehlerbehandlung

[tabs]
====
Sync::
+
[source,python]
----
from ecmind_blue_client.ecm import ECMNotFoundException

try:
    folder = ecm.dms.get(InvoiceFolder, 12345)
    print(folder.Title)
except ECMNotFoundException:
    print("Objekt nicht gefunden")
----

Async::
+
[source,python]
----
from ecmind_blue_client.ecm import ECMNotFoundException

try:
    folder = await ecm.dms.get(InvoiceFolder, 12345)
    print(folder.Title)
except ECMNotFoundException:
    print("Objekt nicht gefunden")
----
====

=== Rechte und Verwaltungsparameter

[tabs]
====
Sync::
+
[source,python]
----
folder = ecm.dms.get(InvoiceFolder, 12345, rights=True, base_params=True)
print(folder.system.rights.edit_metadata)
print(folder.system.base_params.creator)
----

Async::
+
[source,python]
----
folder = await ecm.dms.get(InvoiceFolder, 12345, rights=True, base_params=True)
print(folder.system.rights.edit_metadata)
print(folder.system.base_params.creator)
----
====

=== Dokument mit Dateiinformationen und Varianten

[tabs]
====
Sync::
+
[source,python]
----
doc = ecm.dms.get(InvoiceDocument, 12345, file_properties=True, variants=True)
print(doc.system.file_properties.extension, doc.system.file_properties.size)
for v in doc.system.variants:
    print(v.doc_ver, "aktiv" if v.is_active else "")
----

Async::
+
[source,python]
----
doc = await ecm.dms.get(InvoiceDocument, 12345, file_properties=True, variants=True)
print(doc.system.file_properties.extension, doc.system.file_properties.size)
for v in doc.system.variants:
    print(v.doc_ver, "aktiv" if v.is_active else "")
----
====

=== Dokument-Ortsfelder abrufen (use_result_list)

`folder_id` und `register_id` sind nur mit `use_result_list=True` verfügbar:

[tabs]
====
Sync::
+
[source,python]
----
doc = ecm.dms.get(InvoiceDocument, 12345, use_result_list=True)
print(doc.system.folder_id)    # ID des übergeordneten Ordners
print(doc.system.register_id)  # ID des übergeordneten Registers
----

Async::
+
[source,python]
----
doc = await ecm.dms.get(InvoiceDocument, 12345, use_result_list=True)
print(doc.system.folder_id)
print(doc.system.register_id)
----
====

=== Nur bestimmte Felder laden (use_result_list + fields)

[tabs]
====
Sync::
+
[source,python]
----
folder = ecm.dms.get(
    InvoiceFolder, 12345,
    use_result_list=True,
    fields=[InvoiceFolder.Title, InvoiceFolder.Year],
)
print(folder.Title, folder.Year)
# folder.Status ist None (nicht angefordert)
----

Async::
+
[source,python]
----
folder = await ecm.dms.get(
    InvoiceFolder, 12345,
    use_result_list=True,
    fields=[InvoiceFolder.Title, InvoiceFolder.Year],
)
print(folder.Title, folder.Year)
----
====
