API-Referenz
Die API ist über die ECM()-Factory zugänglich und in folgende Namespaces unterteilt:
| Namespace | Beschreibung | Referenz |
|---|---|---|
|
Ordner-, Register- und Dokumentenoperationen |
|
|
Benutzer- und Gruppenverwaltung |
|
|
Server-Metadaten und Objektdefinitionen |
|
|
Direkter SQL-Zugriff über ADO |
|
|
Mappen (Portfolios) und ihre Inhalte |
1. ECM-Factory
from ecmind_blue_client.ecm import ECM
from ecmind_blue_client.pool import SyncPoolClient
client = SyncPoolClient(servers="<host>:4000:1", username="<username>", password="<password>")
ecm = ECM(client)
Die ECM()-Funktion ist überladen: Ein SyncPoolClient liefert ECMSync, ein AsyncPoolClient liefert ECMAsync.
2. impersonate()
ecm.impersonate(
username: str | None = None,
*,
user_guid: str | None = None,
) -> ECMSync | ECMAsync
Gibt eine neue ECM-Instanz zurück, die alle Anfragen mit dem angegebenen Benutzerkontext ausführt. Der Zielbenutzer kann auf zwei Wege angegeben werden, jeder davon über einen eigenen Serverparameter:
| Argument | Serverparameter |
|---|---|
|
|
|
|
Genau eines der beiden Argumente muss gesetzt sein, andernfalls wird ein ValueError ausgelöst.
Ein str ist immer ein Benutzername, niemals eine GUID — Benutzernamen können nur aus Ziffern bestehen oder wie eine GUID aussehen, deshalb müssen GUIDs explizit über user_guid übergeben werden.
Der ausführende Benutzer benötigt die Systemrolle Kontextwechsel.
2.1. Wenn der Wechsel abgelehnt wird
impersonate() selbst macht keine Serverrunde. Kann der Server den Zielbenutzer nicht
annehmen, wirft der erste Job, der über die zurückgegebene Instanz läuft, eine
ECMImpersonationException. Der Server antwortet in allen diesen Fällen mit dem Sammelcode
-1043332467 und nennt die Ursache nur in seinem Fehlerstack; die Exception liest sie dort
aus und formuliert ihre Meldung selbst, in der dritten Person und mit dem Zielbenutzer, statt
den Servertext weiterzureichen.
| Attribut | Inhalt |
|---|---|
|
Die an |
|
Ein Member von |
|
Der Ursachencode des Servers aus dem Fehlerstack, |
|
Die eigene Zeile des Servers, z. B. |
ECMImpersonationCause |
Stack-Code | Meldung der Exception (<user> ist 'name' oder GUID …) |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Gleicher Text; der Sperrmarker wurde administrativ zurückgesetzt, der Server lehnt trotzdem ab. |
|
|
|
|
|
|
Gemessen auf enaio 12.0: USER_UNKNOWN, LOCKED_BY_FAILED_LOGINS und EXPIRED; die übrigen
Ursachen folgen der Serverreferenz. Der Sammelcode bezieht sich nur auf den Kontextwechsel,
nie auf einen Benutzerparameter des Jobs selbst (etwa UserGUID von mng.GetUserRoles). Der
vollständige Fehlerstack des Servers samt SEH-Dump bleibt über cause erreichbar.
from ecmind_blue_client.ecm import ECMImpersonationCause, ECMImpersonationException
try:
roles = ecm.impersonate("john").security.roles()
except ECMImpersonationException as error:
if error.cause is ECMImpersonationCause.USER_UNKNOWN:
print("Benutzer unbekannt")
else:
print(error) # z. B. "The user account 'john' is blocked; the context switch is not possible."
|
Eine Identifikation über die numerische Benutzer-ID gibt es bewusst nicht.
enaio 12.0 nimmt den Parameter |
Unterstützt sowohl den direkten Aufruf als auch die Verwendung als Context-Manager (with / async with).
-
Sync
-
Async
with ecm.impersonate("john") as ecm_john:
ecm_john.dms.insert(MyFolder(Title="Test"))
async with ecm.impersonate("john") as ecm_john:
await ecm_john.dms.insert(MyFolder(Title="Test"))
Die Angabe über die GUID funktioniert genauso:
ecm_john = ecm.impersonate(user_guid="8A1D1F2E4C7B4A9E8F0D3C5B7A9E1D2F")