Query API: Anforderungen

Diese Seite beschreibt Standard-API-Zugriffe für eine clientseitige Suche und Bereitstellung von Daten des Audit Event Service. Im Detail bedeutet dies das Navigieren in Suchergebnisseiten, die kompakte Suche mit verknüpften FHIR-Ressourcen als auch die Suche unter Nutzung von Vergleichsoperatoren.

Paginierungsfunktion (Pagination)

Der Audit Event Service stellt dem ePA-Client in seiner Antwort Navigationsinformationen in Ergebnisseiten zur Verfügung.

URL-Parameter

Um die Paginierungsfunktion zu implementieren, werden die URL-Parameter _count und _offset verwendet. Der Parameter _count bestimmt die Anzahl der Einträge pro Seite, während _offset das Startelement der Seite angibt. Zusätzlich entscheidet der_total-Parameter, ob die Gesamtanzahl der Einträge in der Antwort enthalten sein soll.

URL-Parameter	Beschreibung	Standardwert
`_count`	Der ePA-Client kann die maximale Anzahl von Elementen festlegen, die auf einer "Seite" (page) der Antwort enthalten sein soll. Das bedeutet, dass der Audit Event Service die Ergebnismenge auf diese maximal angegebene Anzahl beschränkt.	25
`_offset`	Dieser Parameter gibt den (zero-based) Offset des ersten zurückgegebenen Elements in der Sammlung an.	0
`_total`	Dieser Parameter steuert, ob und wie der Audit Event Service die Gesamtanzahl der Suchergebnisse zurückgibt. Folgende Werte können eingestellt werden: `none`, `estimate`, `accurate`.

Werte für _total:

none (Standardwert): Die Gesamtanzahl der Suchtreffer wird nicht angezeigt.
estimate: Die ungefähre Gesamtanzahl der Suchtreffer wird angezeigt.
accurate: Die genaue Gesamtanzahl der Suchtreffer wird angezeigt.

Beispiele

API-Anfrage von zehn Elementen des Ressourcentyps AuditEvent, beginnend mit Element 20 der Liste:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_count=10&_offset=20

API-Anfrage der ersten fünf Elemente:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_count=5

API-Anfrage nur für die Gesamtanzahl der Einträge:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_count=0&_total=accurate

Links zur Seitennavigation

In einem FHIR Search Set Bundle enthält das Attribut link eine Liste von Link-Elementen, die jeweils einem spezifischen Navigationszweck innerhalb des Bundles dienen. Die folgenden Beziehungen werden gemäß den Link Relation Types bereitgestellt.

Attribut	Beschreibung	Anforderung
`self`	Ein Link zur aktuellen Seite der Ergebnisse, der die Abfrage repräsentiert, die diese Ergebnisse generiert hat.	MUSS
`next`	Wird verwendet, um zur nächsten Seite der Ergebnisse zu navigieren, entsprechend der festgelegten Paginierung.	MUSS
`previous`	Ermöglicht die Rückkehr zur vorherigen Ergebnismenge und erleichtert die rückwärtige Navigation durch die Seiten.	MUSS
`first`	Navigiert zur ersten Seite der Suchergebnisse und ermöglicht eine schnelle Navigation zum Anfang der Ergebnisliste.	KANN
`last`	Navigiert zur letzten Seite der Suchergebnisse, um ans Ende der Ergebnisliste zu gelangen.	KANN

Jeder Link enthält eine URL, um das entsprechende Ergebnis-Set abzurufen, das dynamisch basierend auf der Suchanfrage und den Paginierungsparametern wie _count und _offset generiert wird. Diese Links vereinfachen die Navigation des ePA-Clients durch große Suchergebnisse, indem sie die Notwendigkeit manueller Anpassungen der Abfrageparameter eliminieren.

Zu jedem Link können zusätzlich zu den Standardpaginierungsparametern wie _count und _offset auch andere Parameter enthalten sein, die die Paginierung innerhalb des Audit Event Service erleichtern. Ein Beispiel hierfür ist der Parameter stateid, der den aktuellen Zustand der Ergebnisliste repräsentiert. Dies ermöglicht es dem Audit Event Service, die Navigation durch die Ergebnisse effizient zu verwalten, indem der Kontext oder Zustand der Suche erhalten bleibt. Dies ist besonders nützlich, wenn ePA-Clients durch umfangreiche oder komplex strukturierte Ergebnismengen navigieren.

{
    "resourceType": "Bundle",
    "id": "example-searchset-audit-event",
    "type": "searchset",
    "total": 100,
    "link":  [
        {
            "relation": "self",
            "url": "/epa/audit/api/v1/fhir/AuditEvent?_offset=20&_count=10"
        },
        {
            "relation": "previous",
            "url": "/epa/audit/api/v1/fhir/AuditEvent?_offset=10&_count=10"
        },
        {
            "relation": "next",
            "url": "/epa/audit/api/v1/fhir/AuditEvent?_offset=30&_count=10"
        }
    ],
    "entry":  [
        {
            "fullUrl": "https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/AuditEvent/api/v1/fhir/AuditEvent/86604fc1-b356-57e3-8738-8ef36c8d608c",
            "resource": {
                "resourceType": "AuditEvent",
                "id": "86604fc1-b356-57e3-8738-8ef36c8d608c",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2025-01-15T14:43:33.244Z",
                    "profile":  [
                        "https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent"
                    ]
                },
                "source": {
                    "observer": {
                        "display": "Elektronische Patientenakte Fachdienst"
                    },
                    "type":  [
                        {
                            "system": "https://gematik.de/fhir/epa/CodeSystem/epa-auditevent-sourcetype-cs",
                            "code": "XDSSVC",
                            "display": "XDS Document Service"
                        }
                    ]
                },
                "agent":  [
                    {
                        "requestor": true,
                        "type": {
                            "coding":  [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleClass",
                                    "code": "PROV",
                                    "display": "healthcare provider"
                                }
                            ]
                        },
                        "who": {
                            "identifier": {
                                "system": "https://gematik.de/fhir/sid/telematik-id",
                                "value": "1-883110000092404"
                            }
                        },
                        "altId": "1-883110000092404",
                        "name": "Praxis Dr. John Doe"
                    }
                ],
                "type": {
                    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
                    "code": "document"
                },
                "action": "U",
                "recorded": "2025-01-15T14:52:04.928Z",
                "outcome": "0",
                "entity":  [
                    {
                        "name": "Arztbrief4711",
                        "description": "operation:provide-and-register-document-set-b",
                        "detail":  [
                            {
                                "type": "DocumentFormatCode",
                                "valueString": "urn:gematik:ig:Arztbrief:r3.1"
                            }
                        ]
                    }
                ]
            },
            "search": {
                "mode": "match"
            }
        },
        {
            "fullUrl": "https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/AuditEvent/api/v1/fhir/AuditEvent/669699b2-f131-4097-b13d-71413a58aa92",
            "resource": {
                "resourceType": "AuditEvent",
                "id": "669699b2-f131-4097-b13d-71413a58aa92",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2025-01-15T14:43:33.244Z",
                    "profile":  [
                        "https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent"
                    ]
                },
                "source": {
                    "observer": {
                        "display": "Elektronische Patientenakte Fachdienst"
                    },
                    "type":  [
                        {
                            "system": "https://gematik.de/fhir/epa/CodeSystem/epa-auditevent-sourcetype-cs",
                            "code": "MEDICATIONSVC",
                            "display": "Medication Service"
                        }
                    ]
                },
                "agent":  [
                    {
                        "requestor": true,
                        "who": {
                            "identifier": {
                                "system": "https://gematik.de/fhir/sid/telematik-id",
                                "value": "1-000000000000000"
                            }
                        },
                        "type": {
                            "coding":  [
                                {
                                    "system": "http://dicom.nema.org/resources/ontology/DCM",
                                    "code": "110150",
                                    "display": "Application"
                                }
                            ]
                        },
                        "altId": "1-000000000000000",
                        "name": "E-Rezept-Fachdienst"
                    }
                ],
                "type": {
                    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
                    "code": "rest"
                },
                "action": "E",
                "recorded": "2025-01-15T14:52:04.928Z",
                "outcome": "0",
                "entity":  [
                    {
                        "name": "MedicationCancelDispensation",
                        "description": "operation:cancel-dispensation-erp"
                    }
                ]
            },
            "search": {
                "mode": "match"
            }
        },
        {
            "fullUrl": "https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/AuditEvent/api/v1/fhir/AuditEvent/589b9862-7935-42f5-a06b-11a6f35833ee",
            "resource": {
                "resourceType": "AuditEvent",
                "id": "589b9862-7935-42f5-a06b-11a6f35833ee",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2025-07-15T14:43:33.244Z",
                    "profile":  [
                        "https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent"
                    ]
                },
                "source": {
                    "observer": {
                        "display": "Elektronische Patientenakte Fachdienst"
                    },
                    "type":  [
                        {
                            "system": "https://gematik.de/fhir/epa/CodeSystem/epa-auditevent-sourcetype-cs",
                            "code": "XDSSVC",
                            "display": "XDS Document Service"
                        }
                    ]
                },
                "agent":  [
                    {
                        "requestor": true,
                        "who": {
                            "identifier": {
                                "system": "https://gematik.de/fhir/sid/telematik-id",
                                "value": "1-000000000000000"
                            }
                        },
                        "type": {
                            "coding":  [
                                {
                                    "system": "http://dicom.nema.org/resources/ontology/DCM",
                                    "code": "110150",
                                    "display": "Application"
                                }
                            ]
                        },
                        "altId": "1-000000000000000",
                        "name": "Portugal"
                    },
                    {
                        "requestor": true,
                        "extension":  [
                            {
                                "url": "https://gematik.de/fhir/epa/StructureDefinition/epa-healthcare-facility-type-extension",
                                "valueCoding": {
                                    "system": "urn:oid:2.16.840.1.113883.2.9.6.2.7",
                                    "code": "221",
                                    "display": "Medical Doctors"
                                }
                            }
                        ],
                        "type": {
                            "coding":  [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-RoleClass",
                                    "code": "PROV",
                                    "display": "healthcare provider"
                                }
                            ]
                        },
                        "role":  [
                            {
                                "coding":  [
                                    {
                                        "system": "urn:oid:1.3.6.1.4.1.12559.11.10.1.3.2.2.2",
                                        "code": "Resident Physician",
                                        "display": "Resident Physician"
                                    }
                                ]
                            }
                        ],
                        "name": "Dr. Manuel Dos Santos / Clínica de Dos Santos"
                    }
                ],
                "type": {
                    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
                    "code": "rest"
                },
                "action": "R",
                "recorded": "2025-07-15T14:52:04.928Z",
                "outcome": "0",
                "entity":  [
                    {
                        "name": "Patient Summary",
                        "description": "operation:retrieve-document-set"
                    }
                ]
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}

<Bundle xmlns="http://hl7.org/fhir">
    <id value="example-searchset-audit-event" />
    <type value="searchset" />
    <total value="100" />
    <link>
        <relation value="self" />
        <url value="/epa/audit/api/v1/fhir/AuditEvent?_offset=20&amp;_count=10" />
    </link>
    <link>
        <relation value="previous" />
        <url value="/epa/audit/api/v1/fhir/AuditEvent?_offset=10&amp;_count=10" />
    </link>
    <link>
        <relation value="next" />
        <url value="/epa/audit/api/v1/fhir/AuditEvent?_offset=30&amp;_count=10" />
    </link>
    <entry>
        <fullUrl value="https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/AuditEvent/api/v1/fhir/AuditEvent/86604fc1-b356-57e3-8738-8ef36c8d608c" />
        <resource>
            <AuditEvent>
                <id value="86604fc1-b356-57e3-8738-8ef36c8d608c" />
                <meta>
                    <versionId value="1" />
                    <lastUpdated value="2025-01-15T14:43:33.244Z" />
                    <profile value="https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent" />
                </meta>
                <type>
                    <system value="http://terminology.hl7.org/CodeSystem/audit-event-type" />
                    <code value="document" />
                </type>
                <action value="U" />
                <recorded value="2025-01-15T14:52:04.928Z" />
                <outcome value="0" />
                <agent>
                    <type>
                        <coding>
                            <system value="http://terminology.hl7.org/CodeSystem/v3-RoleClass" />
                            <code value="PROV" />
                            <display value="healthcare provider" />
                        </coding>
                    </type>
                    <who>
                        <identifier>
                            <system value="https://gematik.de/fhir/sid/telematik-id" />
                            <value value="1-883110000092404" />
                        </identifier>
                    </who>
                    <altId value="1-883110000092404" />
                    <name value="Praxis Dr. John Doe" />
                    <requestor value="true" />
                </agent>
                <source>
                    <observer>
                        <display value="Elektronische Patientenakte Fachdienst" />
                    </observer>
                    <type>
                        <system value="https://gematik.de/fhir/epa/CodeSystem/epa-auditevent-sourcetype-cs" />
                        <code value="XDSSVC" />
                        <display value="XDS Document Service" />
                    </type>
                </source>
                <entity>
                    <name value="Arztbrief4711" />
                    <description value="operation:provide-and-register-document-set-b" />
                    <detail>
                        <type value="DocumentFormatCode" />
                        <valueString value="urn:gematik:ig:Arztbrief:r3.1" />
                    </detail>
                </entity>
            </AuditEvent>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
    <entry>
        <fullUrl value="https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/AuditEvent/api/v1/fhir/AuditEvent/669699b2-f131-4097-b13d-71413a58aa92" />
        <resource>
            <AuditEvent>
                <id value="669699b2-f131-4097-b13d-71413a58aa92" />
                <meta>
                    <versionId value="1" />
                    <lastUpdated value="2025-01-15T14:43:33.244Z" />
                    <profile value="https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent" />
                </meta>
                <type>
                    <system value="http://terminology.hl7.org/CodeSystem/audit-event-type" />
                    <code value="rest" />
                </type>
                <action value="E" />
                <recorded value="2025-01-15T14:52:04.928Z" />
                <outcome value="0" />
                <agent>
                    <type>
                        <coding>
                            <system value="http://dicom.nema.org/resources/ontology/DCM" />
                            <code value="110150" />
                            <display value="Application" />
                        </coding>
                    </type>
                    <who>
                        <identifier>
                            <system value="https://gematik.de/fhir/sid/telematik-id" />
                            <value value="1-000000000000000" />
                        </identifier>
                    </who>
                    <altId value="1-000000000000000" />
                    <name value="E-Rezept-Fachdienst" />
                    <requestor value="true" />
                </agent>
                <source>
                    <observer>
                        <display value="Elektronische Patientenakte Fachdienst" />
                    </observer>
                    <type>
                        <system value="https://gematik.de/fhir/epa/CodeSystem/epa-auditevent-sourcetype-cs" />
                        <code value="MEDICATIONSVC" />
                        <display value="Medication Service" />
                    </type>
                </source>
                <entity>
                    <name value="MedicationCancelDispensation" />
                    <description value="operation:cancel-dispensation-erp" />
                </entity>
            </AuditEvent>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
    <entry>
        <fullUrl value="https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/AuditEvent/api/v1/fhir/AuditEvent/589b9862-7935-42f5-a06b-11a6f35833ee" />
        <resource>
            <AuditEvent>
                <id value="589b9862-7935-42f5-a06b-11a6f35833ee" />
                <meta>
                    <versionId value="1" />
                    <lastUpdated value="2025-07-15T14:43:33.244Z" />
                    <profile value="https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent" />
                </meta>
                <type>
                    <system value="http://terminology.hl7.org/CodeSystem/audit-event-type" />
                    <code value="rest" />
                </type>
                <action value="R" />
                <recorded value="2025-07-15T14:52:04.928Z" />
                <outcome value="0" />
                <agent>
                    <type>
                        <coding>
                            <system value="http://dicom.nema.org/resources/ontology/DCM" />
                            <code value="110150" />
                            <display value="Application" />
                        </coding>
                    </type>
                    <who>
                        <identifier>
                            <system value="https://gematik.de/fhir/sid/telematik-id" />
                            <value value="1-000000000000000" />
                        </identifier>
                    </who>
                    <altId value="1-000000000000000" />
                    <name value="Portugal" />
                    <requestor value="true" />
                </agent>
                <agent>
                    <extension url="https://gematik.de/fhir/epa/StructureDefinition/epa-healthcare-facility-type-extension">
                        <valueCoding>
                            <system value="urn:oid:2.16.840.1.113883.2.9.6.2.7" />
                            <code value="221" />
                            <display value="Medical Doctors" />
                        </valueCoding>
                    </extension>
                    <type>
                        <coding>
                            <system value="http://terminology.hl7.org/CodeSystem/v3-RoleClass" />
                            <code value="PROV" />
                            <display value="healthcare provider" />
                        </coding>
                    </type>
                    <role>
                        <coding>
                            <system value="urn:oid:1.3.6.1.4.1.12559.11.10.1.3.2.2.2" />
                            <code value="Resident Physician" />
                            <display value="Resident Physician" />
                        </coding>
                    </role>
                    <name value="Dr. Manuel Dos Santos / Cl&#237;nica de Dos Santos" />
                    <requestor value="true" />
                </agent>
                <source>
                    <observer>
                        <display value="Elektronische Patientenakte Fachdienst" />
                    </observer>
                    <type>
                        <system value="https://gematik.de/fhir/epa/CodeSystem/epa-auditevent-sourcetype-cs" />
                        <code value="XDSSVC" />
                        <display value="XDS Document Service" />
                    </type>
                </source>
                <entity>
                    <name value="Patient Summary" />
                    <description value="operation:retrieve-document-set" />
                </entity>
            </AuditEvent>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
</Bundle>

Suche

Die FHIR-Schnittstellen des Audit Event Service unterstützen standardmäßige FHIR-Suchoperationen gemäß den Vorgaben der FHIR-Spezifikation. Bei einer Suche wird ein Search Set Bundle zurückgegeben, das speziell die Ressource AuditEvent konfiguriert ist.

Beispiele Standard-Suchparameter

_id: Bezieht sich auf die logische ID der Ressource

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_id=ea01ccbc-aa5d-4c34-8292-d95678d52c98

_lastUpdated: Kann verwendet werden, um Ressourcen basierend auf dem letzten Änderungszeitpunkt auszuwählen

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_lastUpdated=2025-15-01

Vergleiche und Präzision für Zahlen, Daten und Mengen

Bei einer Suche, die numerische oder Datumsparameter umfasst, hängen die verwendeten Werte von der Präzision des bereitgestellten Parameters ab. Zum Beispiel erstreckt sich für das Datum 2025-02-11 der Bereich von 2025-02-11, um 00:00:00 Uhr (inklusive) bis 2025-02-12, um 00:00:00 Uhr (exklusive).

Präfix

In FHIR werden Gleitkommazahlen durch Datentypen wie decimal und quantity dargestellt, die die Präzision des gespeicherten Werts erfassen. Dies schließt jedoch einige Felder aus, die einfache Ganzzahlen verwenden. Suchoperationen in diesen Feldern führen zu exakten numerischen Übereinstimmungen. Bei numerischen Vergleichen (number, quantity) mit einem einzelnen Wert sind nachfolgende spezifische Präfixe anwendbar. Wenn kein Präfix angegeben wird, wird standardmäßig eq verwendet. Weitere Details finden sich hier: FHIR R4 Search Prefix

Präfix	Beschreibung
`eq`	Der Wert des Parameters in der Ressource ist gleich dem bereitgestellten Wert.
`ne`	Der Wert des Parameters in der Ressource ist nicht gleich dem bereitgestellten Wert.
`gt`	Der Wert des Parameters in der Ressource ist größer als der bereitgestellte Wert.
`lt`	Der Wert des Parameters in der Ressource ist kleiner als der bereitgestellte Wert.
`ge`	Der Wert des Parameters in der Ressource ist größer oder gleich dem bereitgestellten Wert.
`le`	Der Wert des Parameters in der Ressource ist kleiner oder gleich dem bereitgestellten Wert.

Datumsangaben haben einen Bereich, der auf ihrer Präzision (Jahr, Monat, Tag) basiert. Für Typen wie Range oder Period sind eindeutige obere und untere Grenzen definiert. Es gibt spezifische Präfixe für derartige Vergleiche. Wird kein Präfix angegeben, ist eq die Standardwahl.

Präfix	Beschreibung
`eq`	Der Bereich des Suchwerts enthält den Bereich des Zielwerts vollständig.
`ne`	Der Bereich des Suchwerts enthält den Bereich des Zielwerts nicht vollständig.
`gt`	Der Bereich oberhalb des Suchwerts überlappt mit dem Bereich des Zielwerts.
`lt`	Der Bereich unterhalb des Suchwerts überlappt mit dem Bereich des Zielwerts.
`ge`	Der Bereich oberhalb des Suchwerts überlappt mit oder schließt den Bereich des Zielwerts vollständig ein.
`le`	Der Bereich unterhalb des Suchwerts überlappt mit oder schließt den Bereich des Zielwerts vollständig ein.
`sa`	Der Bereich des Parameterwerts beginnt nach dem Zielbereich.
`eb`	Der Bereich des Parameterwerts endet vor dem Zielbereich.

Beispiele

Alle AuditEvents, die vor dem 15. Januar 2025 aktualisiert oder erstellt wurden.

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_lastUpdated=lt2025-15-01T00:00:00Z

Alle AuditEvents nach dem 15. Januar 2025.

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=gt2025-15-01T00:00:00Z

Alle AuditEvents seit dem 15. Januar 2025 und von der Allgemeinarztpraxis "Praxis Dr. John Doe".

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=ge2025-15-01T11:00:00Z&altid=1-883110000092404

Alle AuditEvents ab dem 15. Januar 2025 und alle AuditEvents, die eine Erstellung protokollieren.

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=2025-15-01T11:00:00Z&action=C

Alle AuditEvents für das XDS-Dokument Arztbrief4711.

GET [base]/epa/audit/api/v1/fhir/AuditEvent?entity-name=Arztbrief4711