Table of contents

Berichte und Ereignisse (Vorschau) | Graph-API-Konzepte

Bryan Lamos|Zuletzt aktualisiert: 06.10.2016
|
1 Mitwirkender

Gilt für: Graph-API | Azure Active Directory (AD)

Übersicht und Voraussetzungen

Die Vorschau der REST-API für Azure AD-Berichte und -Ereignisse ermöglicht den schreibgeschützten Zugriff auf Berichte mit Zugriffs- und Nutzungsdaten, die innerhalb eines Azure AD-Mandanten verwaltet werden. Im Artikel Anzeigen von Zugriffs- und Nutzungsberichten finden Sie eine Übersicht zu den verfügbaren Berichtstypen und Informationen dazu, wie Sie auf der Benutzeroberfläche des Azure-Verwaltungsportals auf die Berichtsfunktion zugreifen.

Wichtig

Die Funktionen der Azure AD Graph-API sind auch über Microsoft Graph verfügbar. Dies ist eine einheitliche API, die auch APIs von anderen Microsoft-Diensten wie Outlook, OneDrive, OneNote, Planner und Office Graph enthält. Auf alle wird über einen einzigen Endpunkt mit einem einzigen Zugriffstoken zugegriffen. Beachten Sie, dass Berichte und Ereignisse in Microsoft Graph derzeit nicht unterstützt werden. Sie müssen die Azure AD Graph-API für diese Features verwenden.

Die Verwendung der Berichts- und Ereignis-API-Vorschau erfordert außerdem Kenntnisse in der Authentifizierung und Anwendungskonfiguration in Azure AD. Wenn Sie mit den Konzepten der Azure AD-Authentifizierung und/oder der Möglichkeit, einer Anwendung Berechtigungen für den Zugriff auf Ihren Mandanten zu gewähren, nicht vertraut sind, sollten Sie den Artikel Authentifizierungsszenarien für Azure AD und insbesondere den Abschnitt Grundlagen zur Registrierung einer Anwendung in Azure AD lesen. In diesem zweiten Abschnitt gibt es zudem einen Link zu dem detaillierteren Artikel Integrieren von Anwendungen in Azure Active Directory, einschließlich bestimmter Berechtigungen für den Zugriff auf die Graph-API, sobald Sie soweit sind, dass Sie den Zugriff für Ihre Anwendung konfigurieren können.

Schließlich benötigen Sie Zugriff auf einen Azure AD-Mandanten, sobald Sie soweit sind, dass Sie den Zugriff für Ihre Anwendung konfigurieren können. Auf Github finden Sie eine begleitende ASP.NET-Beispielanwendung namens WebApp-GraphAPI-Reporting. Diese enthält in „readme.md“ schrittweise Anweisungen sowie auf der Hauptseite Azure Active Directory-Codebeispiele eine Übersicht über alle Beispiele, in denen die Verwendung der Active Directory-Authentifizierungsbibliothek (ADAL) und der Graph-API von mehreren Plattformen veranschaulicht wird.

Adressierung

Sobald Sie den Mandanten konfiguriert haben und auf die Berichts- und Ereignis-API zugreifen können, lesen Sie den Artikel Schnellstartanleitung für die Azure AD Graph-API. Dort finden Sie ausführliche Informationen zur Erstellung von Dienst-URLs, HTTP-Anforderungsheadern und zugehörigen OData-Zugriffstoken sowie Informationen zur Verwendung von Testtools (z. B. Graph-Explorer, Fiddler), um Testanforderungen für den Mandanten auszuführen.

Beachten Sie, dass für alle Berichts- und Ereignisvorgänge das folgende OData-kompatible URL-Format verwendet wird, wobei tenant-name der Name des Azure AD-Mandanten und reports/<service-operation> der Pfad zur jeweiligen Berichtsressource ist, die aufgerufen werden soll: https://graph.windows.net/<tenant-name>/reports/<service-operation>?api-version=beta.

Die Berichts- und Ereignis-API unterstützt auch eine Teilmenge der OData-Abfrageoptionen, die von der Graph-Haupt-API unterstützt werden (siehe nächster Abschnitt).

Unterstützte Abfrageoptionen

$filter

Für Filterausdrücke gelten die folgenden Einschränkungen:

  • Der Verlauf aller Berichte umfasst standardmäßig die letzten 30 Tage.

  • Nicht alle Eigenschaften der unterstützten Entitäten können in einem Filterausdruck verwendet werden. Weitere Informationen finden Sie in den Details zu den Eigenschaften für die einzelnen Berichts- und Ereignisentitäten weiter unten in diesem Thema.

  • Logische Operatoren: and wird unterstützt. Beispiel: https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=(eventTime gt 2014-03-01 and eventTime lt 2015-04-23) or eventTime lt 2015-02-01

  • Vergleichsoperatoren: eq (gleich), gt (größer als), ge (größer als oder gleich), lt (kleiner als) und le (kleiner als oder gleich) werden unterstützt.

  • startswith: nicht unterstützt.

  • any: nicht unterstützt.

  • Arithmetische Operatoren: nicht unterstützt.

  • Funktionen: nicht unterstützt.

  • null-Werte werden nicht als Operand in Filterausdrücken unterstützt.

Hinweis: Leerzeichen in der Abfragezeichenfolge sollten URL-codiert werden, bevor eine Anforderung gesendet wird. Die Abfragezeichenfolge https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime gt 2014-03-01 and eventTime lt 2015-04-23 sollte beispielsweise wie folgt URL-codiert werden: https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime%20gt%202014-03-01%20and%20eventTime%20lt%202015-04-23

Beispielanforderungen unter Verwendung der $filter-Abfrageoption:

AnforderungBeschreibung
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime%20eq%202015-03-12T22:01:18.4385955ZGibt eine Liste der Ereignisse aus dem Kontobereitstellungsbericht zurück, die an einem bestimmten Datum und zu einer bestimmten Uhrzeit aufgetreten sind
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$filter=eventTime%20gt%202014-03-01%20and%20eventTime%20lt%202015-04-23Gibt eine Liste der Ereignisse aus dem Kontobereitstellungsbericht zurück, die im angegebenen Bereich aufgetreten sind

$top

$top gibt eine Teilmenge der Einträge für den angegebenen Bericht zurück. Sie besteht aus den ersten N Einträgen, wobei N eine positive ganze Zahl ist. Beispielanforderungen unter Verwendung der $top-Abfrageoption:

AnforderungBeschreibung
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$top=5Gibt die letzten fünf Ereignisse aus dem Kontobereitstellungsbericht zurück

$skip

$skip gibt eine Teilmenge der Einträge für den angegebenen Bericht zurück. Die Teilmenge wird definiert, indem N Einträge gesucht und in die Berichtsauflistung eingefügt und nur die verbleibenden Einträge ausgewählt werden (beginnend ab Eintrag N+1). Beispielanforderungen unter Verwendung der $skip-Abfrageoption:

AnforderungBeschreibung
https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta&$skip=17Gibt die verbleibenden Einträge aus der Ereignissammlung des Kontobereitstellungsberichts ab Eintrag 18 zurück

Dienstmetadaten, Entitäten, Eigenschaften und Vorgänge

Alle Entitäten und Eigenschaften, die von den OData-Berichts- und Ereignisressourcen unterstützt werden, werden im zugehörigen Dienstmetadatendokument angegeben. In diesem Dokument wird das Entity Data Model (EDM) des Diensts mit der standardmäßigen OData Common Schema Definition Language (CSDL) definiert. Sie können die CSDL-Metadaten abrufen, indem Sie dem Ressourcenpfad „/reports“ in der URL das $metadata-Segment hinzufügen: https://graph.windows.net/<tenant-name>/reports/$metadata?api-version=beta. Mit Ausnahme des Segments $metadata wird eine Liste der verfügbaren Berichtsressourcen als JSON-Daten im Antworttext zurückgegeben. Die OData-Dienstvorgänge, die im Ressourcenpfad verwendet werden können, um auf die Ereignisdatensammlungen zuzugreifen, sind durch das Name-Attribut des &ltEntitySet&gt-Elements definiert, das sich in der Nähe des Endes der CSDL befindet. Um zum Beispiel auf die Ereignisdatensammlung zuzugreifen, die mit dem Bericht „Kontobereitstellung“ verknüpft ist, würden Sie eine URL wie die folgende verwenden: https://graph.windows.net/<tenant-name>/reports/accountProvisioningEvents?api-version=beta.

Hinweis: Der Namespace, der die OData-Entitäten definiert, die von der Berichts- und Ereignis-API unterstützt werden, lautet Microsoft.ActiveDirectory.DataService.PublicApi.Model.Reporting. Er unterscheidet sich von dem Namespace, der die Entitäten in der Graph-Haupt-API definiert, der Microsoft.DirectoryServices lautet. Darüber hinaus unterscheidet sich die Berichts- und Ereignis-API in den folgenden wichtigen Punkten von der Graph-Haupt-API:

  • Die Entitäten werden nicht von einem Basistyp abgeleitet und unterstützen keine Navigationseigenschaften.
  • Der Dienst unterstützt keine zusätzlichen Funktionen oder komplexen Typen.
  • Der Dienst unterstützt nur HTTP READ-Vorgänge.

Dieses Thema enthält zusätzliche Details zu den Auflistungen jeder Entität und ihrer zugeordneten Eigenschaften, die nur in Lesevorgängen (HTTP GET) unterstützt werden. Weitere Details zu jeder Entität finden Sie im Artikel Anzeigen von Zugriffs- und Verwendungsberichten.

AllUsersWithAnomalousSignInActivityEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit der irregulären Aktivität.
detailEdm.StringDetails zur Aktivität.
reasonEdm.StringDie anormale Aktivität, wodurch der Benutzer in den Bericht aufgenommen wurde.
idEdm.GuidDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

AccountProvisioningEvent

NameTypRead(GET)Beschreibung
idEdm.StringDer eindeutige Bezeichner für das Ereignis.
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
AnwendungEdm.StringDer Name der Anwendung, die das Bereitstellungsereignis verursacht hat.
instanceNameEdm.StringDer Name der Anwendungsinstanz, die das Bereitstellungsereignis verursacht hat.
operationEdm.StringDer Name des Vorgangs.
sourceTypeEdm.StringDer Typ der Quelle der Aktivität.
targetTypeEdm.StringDer Typ des Ziels der Aktivität.
joiningPropertyEdm.StringDie zum Verknüpfen verwendete Eigenschaft.
addedPropertiesEdm.StringDie Namen der Eigenschaften, die hinzugefügt wurden.
removedPropertiesEdm.StringDie Namen der Eigenschaften, die entfernt wurden.
resultEdm.StringDas Ergebnis des Vorgangs.

ApplicationUsageSummaryEvent

Wichtig

Die Funktion zur Berichterstattung über Anmeldeaktivitäten wird von der Azure Active Directory-API für Berichte über Anmeldeaktivitäten bereitgestellt.

NameTypRead(GET)Beschreibung
idEdm.StringDer eindeutige Bezeichner für das Ereignis.
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
applicationNameEdm.StringDer Anzeigename der Anwendung mit Anmeldeaktivitäten.
uniqueUsersEdm.Int32Die Anzahl der eindeutigen Benutzer, die sich bei der Anwendung angemeldet haben.
signInsEdm.Int32Die Anzahl der Anmeldungen bei der Anwendung.

AuditEvent

Wichtig

Verwenden Sie die in diesem Artikel erwähnte Audit-API.

NameTypRead(GET)Beschreibung
idEdm.StringDer eindeutige Bezeichner für das Ereignis.
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
actorEdm.StringDer Benutzerprinzipalname (User Principal Name, UPN) des agierenden Benutzers (Akteur).
AktionEdm.StringDie spezifische Aktion, die vom Akteur ausgeführt wird. Weitere Informationen zu den möglichen Aktionswerten finden Sie im Artikel „Azure AD-Überwachungsberichtereignisse“.
targetEdm.StringDer Benutzerprinzipalname (User Principal Name, UPN) des Zielbenutzers.
actorDetailEdm.StringZusätzliche Eigenschaftendetails für den agierenden Benutzer, einschließlich UPN, PUID und andere.
targetDetailEdm.StringZusätzliche Eigenschaftendetails für den Zielbenutzer, einschließlich UPN und PUID.
updatedPropertiesEdm.StringEigenschaften, die in einem Aktualisierungsereignis aktualisiert wurden, wie durch die Action-Eigenschaft angegeben.

CompromisedCredentialsEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
credentialTypeEdm.StringDer Anmeldeinformationstyp.
reasonEdm.StringDer Grund, warum das Konto als gefährdet markiert wurde.
idEdm.GuidEin eindeutiger Bezeichner des Benutzers.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

IrregularSignInActivityEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit der irregulären Aktivität.
ipAddressEdm.StringDie IP-Adresse des angemeldeten Computers.
eventClassificationEdm.StringGibt an, ob die Anmeldung als irregulär oder verdächtig eingestuft wird.
GerätEdm.StringInformationen über das Gerät, über das sich der Benutzer angemeldet hat.
reasonEdm.StringDer Grund dafür, dass die Anmeldung als verdächtig gekennzeichnet wurde.
locationEdm.StringDer ungefähre geografische Standort der Anmeldung.
idEdm.GuidDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

MimSsgmGroupActivityEvent

NameTypRead(GET)Beschreibung
idEdm.StringDer eindeutige Bezeichner des Ereignisses.
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
GruppeEdm.StringDie Gruppe, für die die Self-Service-Aktion ausgeführt wurde.
AktionEdm.StringDie Self-Service-Aktion, die für die Gruppe ausgeführt wurde.

MimSsprActivityEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
RolleEdm.StringDie Rolle des Benutzers.
methodsUsedEdm.StringDie Methode, die zum Zurücksetzen des Kennworts des Benutzers verwendet wurde.
resultEdm.StringDas Ergebnis des Versuchs des Benutzers, sein Kennwort zurückzusetzen.
DetailsEdm.StringZusätzliche Informationen zum Versuch des Benutzers, sein Kennwort zurückzusetzen.
idEdm.StringDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

MimSsprRegistrationActivityEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
RolleEdm.StringDie Rolle des Benutzers.
registrationActivityEdm.StringDie Registrierungsaktivität, die vom Benutzer ausgeführt wurde.
idEdm.StringDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

SignInsAfterMultipleFailuresEvent

NameTypRead(GET)Beschreibung
firstSuccessfulSignInEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit der ersten erfolgreichen Anmeldung nach mehreren Versuchen.
failedAttemptsToSignInEdm.Int32Die Anzahl der fehlerhaften Anmeldungen vor der erfolgreichen Anmeldung.
idEdm.GuidDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

SignInsFromIPAddressesWithSuspiciousActivityEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas letzte Datum und die letzte Uhrzeit, zu denen diese Art von Ereignis aufgetreten ist.
ipAddressEdm.StringDie IP-Adresse des angemeldeten Computers.
idEdm.GuidDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

SignInsFromMultipleGeographiesEvent

NameTypRead(GET)Beschreibung
firstSigninFromEdm.StringDer ungefähre Standort der ersten Anmeldung.
secondSigninFromEdm.StringDer ungefähre Standort der zweiten Anmeldung.
timeOfSecondSignInEdm.DateTimeOffsetFilterbarDatum und Uhrzeit der zweiten Anmeldung.
timeBetweenSignInsEdm.StringDer ungefähre Unterschied zwischen den beiden Anmeldeorten.
estimatedTravelHoursEdm.Int32Die geschätzte erforderliche Reisedauer zwischen den beiden Anmeldeorten.
idEdm.GuidDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

SignInsFromPossiblyInfectedDevicesEvent

NameTypRead(GET)Beschreibung
deviceIPAddressEdm.StringDie IP-Adresse, über die die Anmeldung erfolgt ist.
lastSignInTimeEdm.DateTimeOffsetFilterbarDatum und Uhrzeit der letzten Anmeldung.
deviceLocationEdm.StringDer ungefähre geografische Standort der Anmeldung.
ClientEdm.StringInformationen über das potenziell infizierte Gerät.
suspectedInfectionEdm.StringInformationen über die mögliche Infektion.
latestPotentiallySuspiciousActivityEdm.DateTimeOffsetFilterbarDatum und Uhrzeit der Infektion.
idEdm.GuidDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

SignInsFromUnknownSourcesEvent

NameTypRead(GET)Beschreibung
numberOfSigninsEdm.Int32Die Gesamtanzahl der Anmeldungen.
ipAddressEdm.StringDie IP-Adresse des angemeldeten Computers.
timeOfLastSuccessfulSignInEdm.DateTimeOffsetFilterbarDas letzte Datum und die letzte Uhrzeit, zu denen diese Art von Ereignis aufgetreten ist.
idEdm.GuidDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

SsgmGroupActivityEvent

NameTypRead(GET)Beschreibung
idEdm.StringDer eindeutige Bezeichner des Ereignisses.
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
GruppeEdm.StringDie Gruppe, für die die Self-Service-Aktion ausgeführt wurde.
AktionEdm.StringDie Self-Service-Aktion, die für die Gruppe ausgeführt wurde.

SsprActivityEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
RolleEdm.StringDie Rolle des Benutzers.
methodsUsedEdm.StringDie Methode, die zum Zurücksetzen des Kennworts des Benutzers verwendet wurde.
resultEdm.StringDas Ergebnis des Versuchs des Benutzers, sein Kennwort zurückzusetzen.
DetailsEdm.StringZusätzliche Informationen zum Versuch des Benutzers, sein Kennwort zurückzusetzen.
idEdm.StringDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

SsprRegistrationActivityEvent

NameTypRead(GET)Beschreibung
eventTimeEdm.DateTimeOffsetFilterbarDas Datum und die Uhrzeit des Auftretens des Ereignisses.
RolleEdm.StringDie Rolle des Benutzers.
registrationActivityEdm.StringDie Registrierungsaktivität, die vom Benutzer ausgeführt wurde.
idEdm.StringDer eindeutige Bezeichner des Ereignisses.
displayNameEdm.StringDer Anzeigename des Benutzers.
userNameEdm.StringDer Name des Benutzers.

Weitere Ressourcen

© 2017 Microsoft