Verzeichnisschemaerweiterungen | Graph-API-Konzepte

Artikel
01/26/2016

In diesem Thema werden die Verzeichniserweiterungen in der Azure AD Graph-API behandelt, die zum Hinzufügen von Eigenschaften zu Verzeichnisobjekten verwendet werden können, ohne dass ein externer Datenspeicher erforderlich ist. Wenn eine Organisation z. B. eine Branchenanwendung (LOB-Anwendung) verwendet, die eine Skype-ID für jeden Benutzer im Verzeichnis erfordert, kann die Graph-API zum Registrieren einer neuen Eigenschaft mit dem Namen „skypeId“ für das User-Objekt des Verzeichnisses und das anschließende Schreiben eines Werts für einen bestimmten Benutzer in die neue Eigenschaft verwendet werden. In diesem Thema werden die Einschränkungen von Verzeichniserweiterungen erläutert. Sie erfahren außerdem, wie diese in einem Verzeichnis registriert werden, und in Beispielen wird ihre Verwendung in der Graph-API veranschaulicht.

Wichtig

Es wird dringend empfohlen, für den Zugriff auf Azure Active Directory-Ressourcen Microsoft Graph zu verwenden, nicht die Azure AD Graph-API. Wir konzentrieren unsere Entwicklungsarbeit auf Microsoft Graph, weitere Verbesserungen für die Azure AD Graph-API sind nicht geplant. Es gibt einige wenige Szenarien, in denen die Azure AD Graph-API möglicherweise noch geeignet ist. Weitere Informationen finden Sie im Office Dev Center im Blogbeitrag Microsoft Graph or the Azure AD Graph.

Erweiterungsdatentypen

Erweiterungen können nur mithilfe von Version 1.5 oder höher der Graph-API registriert werden. Die folgenden Eigenschaftentypen können registriert werden:

Eigenschaftstyp	Hinweise
Binär	256 Bytes maximal.
Boolesch
DateTime	Muss im ISO 8601-Format angegeben werden. Wird in UTC gespeichert.
Integer	32-Bit-Wert.
LargeInteger	64-Bit-Wert.
Zeichenfolge	256 Zeichen maximal.

Die oben aufgeführten Eigenschaftentypen können für die folgenden Objekte in einem Verzeichnis registriert werden:

Grundlagen zum Registrieren einer Erweiterung

Es ist von großer Wichtigkeit, dass Sie verstehen, wie eine Erweiterungseigenschaft in einem Verzeichnis registriert wird und wie sich das Zustimmungsmodell von Azure AD auf ihre Registrierung auswirkt. Weitere Informationen zur Anwendungszustimmung in Azure AD finden Sie unter Das Consent Framework im Überblick in Integrieren von Anwendungen in Azure Active Directory.

Erweiterungseigenschaften werden für ein Application-Objekt im Verzeichnis des Entwicklers registriert. Nachdem der Anwendung durch einen Benutzer oder Administrator im Verzeichnis des Entwicklers zugestimmt wurde, wird die Eigenschaft dem Zielverzeichnistyp hinzugefügt, und es kann im Verzeichnis des Entwicklers sofort darauf zugegriffen werden. Bei einer mehrinstanzenfähigen Anwendung kann auf die Erweiterungseigenschaften für den Zielverzeichnistyp im Verzeichnis einer anderen Organisation sofort zugegriffen werden, wenn der Anwendung durch einen Benutzer oder Administrator in der anderen Organisation zugestimmt wird.

Wenn eine Organisation "schreibgeschützten" Berechtigungen für eine Anwendung mit registrierten Erweiterungen zustimmt, kann auf die Eigenschaften im Verzeichnis der anderen Organisation dennoch zugegriffen werden. Außerdem kann auf Erweiterungseigenschaften durch jede Anwendung in einer Organisation zugegriffen werden, der zugestimmt wurde – nicht nur durch die Anwendung, für die sie registriert sind. Andere Anwendungen in dieser Organisation, denen zugestimmt wurde, können Werte für die neue Erweiterungseigenschaft lesen oder schreiben, wenn sie über ausreichende Berechtigungen verfügen.

Wenn die Anwendung im Verzeichnis der anderen Organisation gelöscht oder die Zustimmung entfernt wird, kann auf die Erweiterungseigenschaft für das Zielverzeichnisobjekt nicht mehr zugegriffen werden. Wenn die Erweiterung von der Anwendung gelöscht wird, kann ebenfalls für das Zielverzeichnisobjekt nicht mehr auf sie zugegriffen werden. Wenn eine mehrinstanzenfähige Anwendung zusätzliche Erweiterungseigenschaften hinzufügt, nachdem die Zustimmung erteilt wurde, kann auf diese Eigenschaften im Verzeichnis der anderen Organisation sofort zugegriffen werden.

Hinweis: Wenn der Wert einer Erweiterungseigenschaft für ein Objekt festgelegt ist und auf diese Eigenschaft im Verzeichnis des Objekts nicht mehr zugegriffen werden kann, wird die Eigenschaft dennoch im Hinblick auf den Grenzwert von 100 Erweiterungseigenschaftswerten dieses Objekts mitgezählt. Nur nachdem der Eigenschaftswert explizit auf NULL festgelegt wurde, wird der Eigenschaftswert nicht mehr mitgezählt. Dies ist nicht möglich, wenn auf die Erweiterungseigenschaft nicht zugegriffen werden kann.

Beispielszenario

Betrachten Sie das folgende Szenario: Litware ist ein unabhängiger Softwarehersteller (ISV), der eine SaaS-Anwendung für die Verwendung durch andere Organisationen entwickelt hat. Diese Anwendung erfordert eine Erweiterungseigenschaft mit dem Namen skypeId für ein User-Objekt. Litware registriert die Anwendung zuerst im Verzeichnis der eigenen Organisation. Dann wird die Graph-API aufgerufen, um die Erweiterungseigenschaft für das Application-Objekt zu registrieren, was bewirkt, dass auf die Eigenschaft für User-Objekte im Verzeichnis von Litware zugegriffen werden kann. Schließlich wandelt Litware die Anwendung in eine mehrinstanzenfähige Anwendung um, damit sie in anderen Organisationen verwendet werden kann.

Contoso mochte die SaaS-Anwendung von Litware einsetzen. Ein Benutzer oder Administrator in Contoso stimmt also der Anwendung zu. Nach der Zustimmung wird die Anwendung im Verzeichnis von Contoso registriert, und die von Litware für die Anwendung registrierten Erweiterungseigenschaften werden sofort im Verzeichnis „Contoso“ verfügbar. Da die skypeId-Erweiterungseigenschaft eines User-Objekts von Litware für die Anwendung registriert wurde, kann auf die Eigenschaft für User-Objekte im Verzeichnis von Contoso zugegriffen werden. Die Anwendung von Litware kann jetzt entsprechend den Berechtigungen, die für die Anwendung im Verzeichnis von Contoso konfiguriert sind, auf die neue Eigenschaft zugreifen. Dies gilt auch für andere Anwendungen im Verzeichnis von Contoso, denen zugestimmt wurde. Dies bedeutet, dass Anwendungen entsprechend ihren Berechtigungen einen Wert für die Erweiterungseigenschaft für einen oder mehrere Benutzer im Verzeichnis schreiben können. Diese Eigenschaft für nur für diejenigen Benutzer im User-Objekt zurückgegeben, für die ein skypeId-Wert geschrieben wurde. Das ist der Fall, bis die skypeId -Eigenschaft auf null festgelegt wird. Danach gibt das User-Objekt für diesen Benutzer die Eigenschaft nicht mehr zurück.

REST-Beispielanforderungen für Verzeichniserweiterungen

Die folgenden Beispielanforderungen zeigen, wie Erweiterungen in Ihrem Verzeichnis registriert, angezeigt, geschrieben, gelesen und gefiltert werden bzw. wie eine Registrierung aufgehoben wird. Ersetzen Sie den Platzhalter <applicationObjectId> durch die Objekt-ID der registrierten Anwendung. Sie können diesen Wert auf folgende Weise abrufen:

Navigieren Sie zu https://graphexplorer.cloudapp.net/, klicken Sie in der oberen rechten Ecke auf den Link Sign In (Anmelden), und melden Sie sich dann mithilfe der Anmeldeinformationen für ein Administratorkonto im Verzeichnis Ihrer Organisation an.
Nachdem Sie sich angemeldet haben, klicken Sie auf die URL im Textfeld für die Ressource (neben der Schaltfläche GET), wählen Sie die URL aus, die mit „applications/“ endet, und klicken Sie dann auf GET, oder drücken Sie die EINGABETASTE.
Suchen Sie in den Ergebnissen nach dem gewünschten Anwendungseintrag, und kopieren Sie dann dessen objectId-Wert wie im folgenden Beispiel gezeigt: „objectId: 269fc2f7-6420-4ea4-be90-9e1f93a87a64“

Dieser Abschnitt enthält Beispielanforderungen für die folgenden Vorgänge:

Registrieren einer Erweiterung
Anzeigen registrierter Erweiterungen
Schreiben eines Erweiterungswerts
Entfernen eines Erweiterungswerts
Lesen eines Erweiterungswerts
Filtern eines Erweiterungswerts
Aufheben der Registrierung einer Erweiterung

Vollständige Beispiele mit Erweiterungseigenschaften finden Sie in den folgenden Azure AD-Beispielen auf GitHub:

WebApp-GraphAPI-DirectoryExtensions-PHP: Veranschaulicht das Erstellen und Verwenden von Erweiterungen mit PHP.
WebApp-GraphAPI-DirectoryExtensions-DotNet: Zeigt ein Organigramm für einen AAD-Mandanten an und ermöglicht das direkte Lesen von Erweiterungswerten.

Registrieren einer Erweiterung

Die folgende Beispielanforderung erstellt eine extensionProperty für das gewünschte Application-Objekt.

Anforderungsformat

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

{
    "name": "<extensionPropertyName>",
    "dataType": "<String or Binary>",
    "targetObjects": [
        "<DirectoryObject>"
    ]
}

Beispielanforderung

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 104

{
    "name": "skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Wenn der Vorgang erfolgreich war, wird ein Statuscode "HTTP 201 Created" zusammen mit dem vollqualifizierten Namen der Erweiterungseigenschaft zurückgegeben, der zum Schreiben von Werten in den Zieltyp verwendet werden kann.

Beispielantwort

HTTP/1.1 201 Created
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty/@Element",
    "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "objectType": "ExtensionProperty",
    "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
    "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Anzeigen registrierter Erweiterungen

Die folgende Beispielanforderung ruft die Erweiterungen ab, die für das Application-Objekt registriert sind.

Anforderungsformat

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

Beispielanforderung

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Wenn der Vorgang erfolgreich war, wird der Statuscode „HTTP 200 OK“ zusammen mit sämtlichen Informationen zu jeder Erweiterungseigenschaft zurückgegeben, die für das Application-Objekt registriert ist.

Beispielantwort

HTTP/1.1 200 OK
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "value": [
        {
            "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
            "objectType": "ExtensionProperty",
            "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "dataType": "String",
            "targetObjects": [
                "User"
            ]
        }
    ]
}

Schreiben eines Erweiterungswerts

Die folgende Beispielanforderung schreibt einen Erweiterungswert für die *skypeId^-Erweiterungseigenschaft für ein User-Objekt.

Anforderungsformat

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": <value>
}

Beispielanforderung

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Wenn der Vorgang erfolgreich war, wird ein Statuscode "HTTP 204 No Content" zurückgegeben.

Beispielantwort

HTTP/1.1 204 No Content

Wenn der versuchte Schreibvorgang den Grenzwert von 100 Erweiterungswerten für das Objekt überschreitet, wird die Antwort „HTTP 403 Verboten“ mit dem Fehlercode Directory_ResourceSizeExceeded und der Meldung „Die maximale Größe des Objekts wurde überschritten. Verringern Sie die Anzahl der Werte, und wiederholen Sie die Anforderung“ angezeigt.

entfernen eines Erweiterungswerts

Die folgende Beispielanforderung entfernt einen Erweiterungswert, der zuvor für die skypeID-Erweiterungseigenschaft für ein User-Objekt festgelegt war, indem der Wert auf null festgelegt wird.

Anforderungsformat

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": null
}

Beispielanforderung

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": null
}

Wenn der Vorgang erfolgreich war, wird ein Statuscode "HTTP 204 No Content" zurückgegeben.

Beispielantwort

HTTP/1.1 204 No Content

Lesen eines Erweiterungswerts

Die folgende Beispielanforderung führt einen einfachen GET-Vorgang für den Benutzer aus, der die Standardeigenschaftenwerte sowie den Wert der neuen Erweiterungseigenschaft zurückgibt.

Anforderungsformat

GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

Beispielanforderung

GET https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Wenn der Vorgang erfolgreich war, wird ein Statuscode "HTTP 200 OK" zusammen mit dem Wert der neuen Erweiterungseigenschaft zurückgegeben (zahlreiche Benutzereigenschaften wurden aus der Beispielantwort entfernt, um die Antwort kurz zu halten).

Beispielantwort

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Filtern eines Erweiterungswerts

Die folgende Beispielanforderung filtert die Benutzer anhand des angegebenen Werts der Erweiterungseigenschaft.

Hinweis: Die Präfixsuche für Erweiterungen ist auf 71 Zeichen für die Zeichenfolgensuche und auf 207 Bytes für die Suche nach binären Erweiterungen beschränkt.

Anforderungsformat

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1

Beispielanforderung

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=extension_ab603c56068041afb2f6832e2a17e237_skypeId%20eq%20'jimbob.skype' HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Wenn der Vorgang erfolgreich war, wird ein Statuscode "HTTP 200 OK" zusammen mit dem sich ergebenden Benutzerobjekt zurückgegeben.

Beispielantwort

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Aufheben der Registrierung einer Erweiterung

Die folgende Beispielanforderung hebt die Registrierung einer Erweiterung durch Ausführen eines DELETE-Vorgangs für die Erweiterungsobjekt-ID auf.

Anforderungsformat

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1

Beispielanforderung

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties/dc893d45-a75b-4ccf-9b92-ce7d80922aa7?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Wenn der Vorgang erfolgreich war, wird ein Statuscode "HTTP 204 No Content" zurückgegeben, und die Registrierung der Erweiterungseigenschaft wird für die Anwendung aufgehoben.

Beispielantwort

HTTP/1.1 204 No Content

Erweiterungsverhalten und Einschränkungen

Erweiterungseigenschaften in einem Verzeichnis weisen das folgende Verhalten auf, und für sie gelten die folgenden Einschränkungen:

Für eine Anwendung registrierte Erweiterungseigenschaften werden in einem Verzeichnis verfügbar, wenn ein Verzeichnisbenutzer oder Administrator der Anwendung zustimmt.
Nachdem eine Erweiterungseigenschaft in einem Verzeichnis verfügbar wurde, kann jede Anwendung, der zugestimmt wurde, einen Wert für diese Erweiterungseigenschaft lesen oder schreiben, und zwar für jedes der Objekte, auf das die Eigenschaft entsprechend den Berechtigungen der Anwendung im Verzeichnis angewendet werden kann. Die Objekte, auf die die Erweiterungseigenschaft angewendet werden kann, sind in der targetObjects-Eigenschaft angegeben.
Für ein einzelnes Objekt in einem Verzeichnis können maximal 100 Erweiterungseigenschaftswerte geschrieben werden. Nehmen wir beispielsweise an, dass für keinen Benutzer in einem Verzeichnis weitere Erweiterungseigenschaftswerte geschrieben wurden. Wenn dann eine Anwendung einen Erweiterungseigenschaftswert für user1 schreibt, können von dieser Anwendung oder einer anderen Anwendung mit entsprechenden Berechtigungen im Verzeichnis Werte für 99 weitere Erweiterungseigenschaften für user1 geschrieben werden. Für andere Benutzer im Verzeichnis können jedoch immer noch 100 Erweiterungseigenschaftswerte geschrieben werden.
Wenn eine Anwendung versucht, einen Wert für eine zusätzliche Erweiterungseigenschaft für ein Objekt festzulegen, für das bereits 100 Erweiterungseigenschaftswerte festgelegt wurden, gibt die Graph-API die Antwort 403 Forbidden mit dem Fehlercode Directory_ResourceSizeExceeded und der folgenden Meldung zurück: „Die maximale Größe des Objekts wurde überschritten. Verringern Sie die Anzahl der Werte, und wiederholen Sie die Anforderung“ angezeigt.
Wenn ein Entwickler die Registrierung einer Erweiterungseigenschaft bei einer Anwendung aufhebt (die Erweiterung aus der Anwendung löscht), ist sofort kein Zugriff mehr auf die Erweiterungseigenschaft im Entwicklerverzeichnis und in den Verzeichnissen, für die der Anwendung die Zustimmung erteilt wurde, möglich.
Wenn die Anwendung aus dem Entwicklerverzeichnis entfernt wird, kann sofort auf alle Erweiterungseigenschaften, die für diese Anwendung registriert sind, im Entwicklerverzeichnis und in den Verzeichnissen, für die der Anwendung die Zustimmung erteilt wurde, nicht mehr zugegriffen werden.
Wenn einer mehrinstanzenfähigen Anwendung in einem Verzeichnis die Zustimmung erteilt wurde und später die Registrierung der Anwendung beim Verzeichnis aufgehoben (aus dem Verzeichnis entfernt) wird, z. B. durch einen Administrator mithilfe des Azure-Verwaltungsportals, kann sofort auf keine der für diese Anwendung registrierten Erweiterungseigenschaften in diesem Verzeichnis mehr zugegriffen werden.
Um einen Erweiterungseigenschaftswert aus einem Verzeichnisobjekt zu entfernen, muss dieser explizit auf null festgelegt werden. Wenn ein Erweiterungseigenschaftswert für ein Verzeichnisobjekt festgelegt ist und aus einem der oben genannten Gründe nicht mehr auf ihn im Verzeichnis zugegriffen werden kann, ist er nicht mehr in diesem Verzeichnisobjekt sichtbar. Er wird jedoch weiterhin bezüglich der Einhaltung des Grenzwerts von 100 Erweiterungseigenschaftswerten für dieses Objekt mitgezählt. Auf den Wert kann weder für Lese- noch für Schreibvorgänge zugegriffen werden, bis die Erweiterungseigenschaft wieder verfügbar gemacht wurde, z.B. indem der Anwendung erneut die Zustimmung erteilt wurde.

Zusätzliche Ressourcen

Referenz zur Azure AD Graph-API