Rozszerzenia schematu katalogu | Pojęcia dotyczące interfejsu API programu Graph
W tym temacie omówiono rozszerzenia katalogów w interfejsie API Azure AD Graph, którego można użyć w celu dodania właściwości do obiektów katalogu bez konieczności magazynu danych zewnętrznych. Na przykład jeśli organizacja ma wiersza aplikacji biznesowych (LOB), która wymaga identyfikatora użytkownika Skype dla każdego użytkownika w katalogu, interfejsu API programu Graph można zarejestrować nową właściwość o nazwie skypeId obiektu użytkownika w katalogu, a następnie zapisać nowe właściwości dla wartości określony użytkownik. W tym temacie ułatwią zrozumienie ograniczeń rozszerzenia katalogów, sposób ich zostanie zarejestrowany w katalogu i zawierają przykłady sposobu ich używania w interfejsu API programu Graph.
Ważne
Zdecydowanie zaleca się używanie Microsoft Graph zamiast interfejsu API Azure AD Graph dostęp do zasobów usługi Azure Active Directory. Nasze programistycznych teraz jest skoncentrowana na program Microsoft Graph i interfejsu API usługi Azure AD Graph planowane żadne rozszerzenia funkcjonalności. Istnieje bardzo ograniczoną liczbę scenariuszy, w których interfejsu API usługi Azure AD Graph nadal może być odpowiednie; Aby uzyskać więcej informacji, zobacz Microsoft Graph lub Azure AD Graph wpis w blogu w Centrum deweloperów pakietu Office.
Typy danych rozszerzenia
Rozszerzenia mogą być rejestrowane tylko przy użyciu interfejsu API programu Graph w wersji 1.5 lub nowszej. Można zarejestrować następujących właściwości:
| Typ właściwości | Uwagi |
|---|---|
| Binarny | Maksymalna liczba 256 bajtów. |
| Boolean | |
| Data i godzina | Należy określić w formacie ISO 8601. Będą przechowywane w formacie UTC. |
| Integer | 32-bitowa wartość. |
| LargeInteger | 64-bitowa wartość. |
| String | maksymalnie 256 znaków. |
Typy właściwości powyżej można zarejestrować na następujące obiekty w katalogu:
Zrozumienie, jak rozszerzenie jest zarejestrowane
To zrozumieć, jak właściwość rozszerzenia jest zarejestrowany w katalogu i jak Azure AD w modelu zgody ma wpływ na jego rejestracji. Aby uzyskać więcej informacji o zgodę aplikacji w usłudze Azure AD, zobacz omówienie Framework zgody w integracji aplikacji z usługą Azure Active Directory.
Właściwości rozszerzenia są rejestrowane na aplikacji obiektu w katalogu dewelopera. Po aplikacji został zgodził się przez użytkownika lub administratora w katalogu dewelopera, właściwość zostanie dodany do typu katalogu docelowego i staje się natychmiast dostępne w katalogu dewelopera. W przypadku aplikacji wielodostępnej aplikacji udzielono zgody przez użytkownika lub administratora w innej organizacji, właściwości rozszerzenia staje się natychmiast dostępna w typie docelowym katalogu w katalogu Twojej organizacji.
Jeśli organizacja wyraża zgodę na "tylko do odczytu" uprawnień dla aplikacji z zarejestrowanych rozszerzeń, właściwości nadal będzie dostępny w katalogu Twojej organizacji. Ponadto właściwości rozszerzenia są dostępne przez dowolną aplikację przyzwolenie w organizacji, nie tylko dla aplikacji, do którego zostały one zarejestrowane. Inne aplikacje przyzwolenie w tej organizacji można odczytu lub zapisu wartości dla nowych właściwości rozszerzenia, jeśli mają wystarczające uprawnienia.
Jeśli aplikacja została usunięta lub zgody zostanie usunięta w katalogu Twojej organizacji, wartość właściwości rozszerzenia stanie się niedostępna obiektu katalogu docelowego. Jeśli rozszerzenie zostanie usunięty przez aplikację, również staje się niedostępny obiektu katalogu docelowego. Jeśli aplikacji wielodostępnych dodaje właściwości dodatkowe rozszerzenia po przyznaniu zgody, te właściwości stają się natychmiast dostępny w katalogu Twojej organizacji.
Uwaga: wartość właściwości rozszerzenia jest ustawiona na obiekt tej właściwości staje się niedostępny w katalogu tego obiektu, właściwość nadal jest za mała limit 100 wartości właściwości rozszerzenia tego obiektu. Jedynym sposobem po jego ustawieniu, usuń wartość właściwości z zagadnieniem jest jawnie ustawiona na wartość null. Nie można tego zrobić, jeśli właściwość rozszerzenia jest niedostępny.
Przykładowy scenariusz
Rozważmy następujący scenariusz: Litware jest niezależny dostawca oprogramowania (ISV), która opracowała aplikacji SaaS w przypadku innych organizacji do używania, a ta aplikacja wymaga właściwości rozszerzenia o nazwie skypeId na koncie użytkownika obiekt. Litware najpierw rejestruje aplikację w własny katalog, a następnie interfejsu API programu Graph jest wywoływana w celu zarejestrowania właściwość rozszerzenia na aplikacji obiektu, który sprawia, że właściwości dostępne dla obiektów użytkownika w katalogu Litware's. Na koniec Litware sprawia, że wielodostępnych aplikacji obsługujących tak, aby można go z innych organizacji.
Firma Contoso chce korzystać z aplikacji SaaS Litware's, więc użytkownik lub administrator w firmie Contoso zgadza się na aplikacji. Po zgodę aplikacja jest zarejestrowany w katalogu firmy Contoso i właściwości rozszerzenia zarejestrowane dla aplikacji przez Litware natychmiast staną się dostępne w katalogu firmy Contoso. Ponieważ skypeId właściwość rozszerzenia dla obiektu użytkownika został zarejestrowany przez Litware w aplikacji, właściwość staje się dostępny na użytkownika obiekty w katalogu firmy Contoso. Litware's aplikacji lub inne przyzwolenie aplikacje w katalogu firmy Contoso mają teraz dostęp do nowej właściwości zgodnie z uprawnieniami skonfigurowane dla tej aplikacji w katalogu firmy Contoso. Oznacza to, aplikacji, zgodnie z ich uprawnieniami mogą zapisywać wartość tej właściwości rozszerzenia na co najmniej jednego użytkownika w katalogu. Tylko użytkownicy, dla którego skypeId wartość została zapisana zwróci tej właściwości na ich użytkownika obiektu. Będzie to miało miejsce do skypeId właściwość jest ustawiona na null, po czasu obiektu użytkownika dla tego użytkownika już nie zwróci właściwości.
Próbki żądań REST dla rozszerzenia katalogów
Następujące żądania przykładowych pokazano, jak zarejestrować, wyświetlanie zapisu, odczytu, filtrować i wyrejestruj rozszerzenia w katalogu. Zastąp <applicationObjectId> symbol zastępczy identyfikatora aplikacji zarejestrowanego obiektu. Tę wartość można uzyskać w następujący sposób:
- Przejdź do https://graphexplorer.cloudapp.net/, kliknij przycisk logowania połączyć w prawym górnym rogu, a następnie zaloguj się przy użyciu poświadczeń konta administratora w katalogu organizacji.
- Po zalogowaniu się kliknij adres URL w polu tekstowym zasobów (obok pozycji UZYSKAĆ przycisku) i wybierz adres URL, który kończy się w aplikacjach / kliknięcie UZYSKAĆ lub kliknij przycisk wprowadź klucz.
- Znajdź pozycję żądanej aplikacji z wyników, a następnie skopiuj jej objectId wartości, takie jak następujące: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"
W tej sekcji są próbki żądań następujące operacje:
- Zarejestruj rozszerzenie
- Wyświetlanie zarejestrowanych rozszerzeń
- Zapisać wartości rozszerzenia
- Usuń wartość rozszerzenia
- Wartość rozszerzenia do odczytu
- Wartość rozszerzenia filtru
- Rozszerzenia wyrejestrować
Dla pełnej próbek używających właściwości rozszerzenia zobacz następujące przykłady w przykładach usługi Azure AD w witrynie Github:
- Aplikacja sieci Web-GraphAPI-DirectoryExtensions-PHP: pokazano, jak utworzyć i użyć rozszerzeń PHP.
- Aplikacja sieci Web-GraphAPI-DirectoryExtensions-DotNet: Wyświetla schemat organizacyjny dzierżawy usługi AAD i umożliwia odczytywanie wartości rozszerzenia dodatkowych zabiegów.
Zarejestruj rozszerzenie
Następujące przykładowe żądanie, tworzy extensionProperty na żądaną aplikacji obiektu.
Format żądania
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>"
]
}
Przykładowe żądanie
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"
]
}
Jeśli operacja zakończyła się powodzeniem, zwróci kod stanu HTTP 201 utworzona wraz z rozszerzenia w pełni kwalifikowana nazwa właściwości, używany do zapisywania wartości na typ docelowy.
Przykładowa odpowiedź
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"
]
}
Wyświetlanie zarejestrowanych rozszerzeń
Następujące przykładowe żądanie pobiera rozszerzeń, które są zarejestrowane na Twojej aplikacji obiektu.
Format żądania
GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1
Przykładowe żądanie
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
Jeśli operacja zakończyła się powodzeniem, zwróci kod stanu HTTP 200 OK oraz wszystkie informacje dotyczące każdej właściwości rozszerzenia zarejestrowane na obiekt aplikacji.
Przykładowa odpowiedź
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"
]
}
]
}
Zapisać wartości rozszerzenia
Następujące przykładowe żądanie zapisuje wartość rozszerzenia * skypeId ^ właściwość rozszerzenia na użytkownika obiektu.
Format żądania
PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
{
"<extensionPropertyName>": <value>
}
Przykładowe żądanie
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"
}
Jeśli operacja zakończyła się powodzeniem, zwróci kod stanu HTTP 204 bez zawartości.
Przykładowa odpowiedź
HTTP/1.1 204 No Content
Jeśli próba zapisu przekracza limit wartości 100 rozszerzenia dla obiektu, zwróci odpowiedzi HTTP 403 — Dostęp zabroniony z kodem błędu "Directory_ResourceSizeExceeded" i następujący komunikat: "rozmiar obiektu przekroczył limit. Zmniejsz liczbę wartości i ponów próbę wykonania żądania".
Usuń wartość rozszerzenia
Następujące przykładowe żądanie Usuwa wartość rozszerzenia, która wcześniej została ustawiona na skypeId właściwość rozszerzenia na użytkownika obiektu przez ustawienie wartości null.
Format żądania
PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
{
"<extensionPropertyName>": null
}
Przykładowe żądanie
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
}
Jeśli operacja zakończyła się powodzeniem, zwróci kod stanu HTTP 204 bez zawartości.
Przykładowa odpowiedź
HTTP/1.1 204 No Content
Wartość rozszerzenia do odczytu
Następujące przykładowe żądanie wykonuje operację GET prostego na użytkownika, które zostaną zwrócone wartości właściwości standardowych, jak i nowa wartość właściwości rozszerzenia.
Format żądania
GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Przykładowe żądanie
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
Jeśli operacja zakończyła się powodzeniem, zwróci kod stanu HTTP 200 OK wraz z nową wartość właściwości rozszerzenia (wiele właściwości użytkownika zostały usunięte z przykładowa odpowiedź w celu jego skrócenia).
Przykładowa odpowiedź
HTTP/1.1 200 OK
{
...
"usageLocation": null,
"userPrincipalName": "Jim@contoso.onmicrosoft.com",
"userType": "Member"
"extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}
Wartość rozszerzenia filtru
Następujące przykładowe żądanie filtruje użytkowników o określonym rozszerzeniu wartość właściwości.
Uwaga: prefiks wyszukiwania dla rozszerzeń są ograniczone do 71 znaków do ciągu wyszukiwania i 207 bajtów do wyszukiwania na binarne rozszerzenia.
Format żądania
GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1
Przykładowe żądanie
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
Jeśli operacja zakończyła się powodzeniem, zwróci kod stanu HTTP 200 OK wraz z wynikowy obiekt użytkownika.
Przykładowa odpowiedź
HTTP/1.1 200 OK
{
...
"usageLocation": null,
"userPrincipalName": "Jim@contoso.onmicrosoft.com",
"userType": "Member"
"extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}
Rozszerzenia wyrejestrować
Następujące przykładowe żądanie wyrejestrowuje właściwość rozszerzenia za pomocą operacji DELETE na identyfikatora obiektu rozszerzenia.
Format żądania
DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1
Przykładowe żądanie
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
Jeśli operacja zakończyła się powodzeniem, zwróci HTTP 204 nr zawartości kod stanu, a właściwość rozszerzenia zostanie wyrejestrowane w aplikacji.
Przykładowa odpowiedź
HTTP/1.1 204 No Content
Zachowania rozszerzeń i ograniczenia
Następujące zachowanie i ograniczenia mają zastosowanie do właściwości rozszerzenia w katalogu:
Właściwości rozszerzenia zarejestrowane dla aplikacji stają się dostępne w katalogu, po katalogu użytkownik lub administrator wyrazi na to zgody dla aplikacji.
Gdy właściwość rozszerzenia stanie się dostępny w katalogu, wszelkie przyzwolenie aplikacji może odczytu lub zapisu wartość tej właściwości rozszerzenia dla wszystkich obiektów, dla którego właściwość jest stosowana zgodnie z uprawnieniami tę aplikację w katalogu. Obiekty, dla których ma zastosowanie właściwości rozszerzenia są określony we właściwości targetObjects.
Mogą być zapisane maksymalnie 100 rozszerzenia wartości właściwości określonego obiektu w katalogu. Na przykład przy założeniu, że nie inne wartości właściwości rozszerzenia zostały zapisane na każdy użytkownik w katalogu, jeśli aplikacja zapisuje wartość właściwości rozszerzenia Użytkownik1, następnie wartości 99 właściwości rozszerzenia może zapisywać do użytkownika Użytkownik1 w tej aplikacji lub inny Aplikacja o odpowiednie uprawnienia w katalogu. jednak nadal będą może zawierać maksymalnie 100 wartości właściwości rozszerzenia zapisywane do nich innym użytkownikom w katalogu.
Jeśli aplikacja próbuje ustawić wartości właściwości dodatkowe rozszerzenia dla obiekt, dla których 100 rozszerzenia zostały już ustawione wartości właściwości, zwraca interfejs API programu Graph 403 Zabroniony odpowiedzi z kodem błędu "Directory_ ResourceSizeExceeded"i następujący komunikat:"rozmiar obiektu przekroczył limit. Zmniejsz liczbę wartości i ponów próbę wykonania żądania".
Projektant wyrejestrowuje (usuwa) właściwość rozszerzenia z aplikacji, natychmiast właściwości rozszerzenia staje się niedostępny w katalogu deweloperów, a także w katalogach, dla których aplikacja udzielono zgody.
Jeśli aplikacja zostanie usunięty z katalogu dewelopera, wszystkie właściwości rozszerzenia zarejestrowany do tej aplikacji natychmiast stać się niedostępne w katalogu deweloperów i katalogi, w których ta aplikacja udzielono zgody.
Jeśli aplikacja wielodostępne udzielono zgody w katalogu i że aplikacja jest później wyrejestrowany (usuwane) z tego katalogu — na przykład, przez administratora przy użyciu portalu zarządzania platformy azure —, a następnie wszelkie zarejestrowane na właściwości rozszerzenia aplikację natychmiast stać się niedostępne w tym katalogu.
Wartość właściwości rozszerzenia musi być wyraźnie ustawione jako null celu usunięte z obiektu katalogu. Jeśli ustawiono wartość właściwości rozszerzenia do obiektu katalogu i właściwość rozszerzenia staje się niedostępny w katalogu z powodów wymienionych powyżej, wartość właściwości rozszerzenia nie będą widoczne dla tego obiektu katalogu. Go jednak nadal odliczona limit wartości właściwości 100 rozszerzenie dla tego obiektu. Do czasu dostępności właściwości rozszerzenia przywróceniu — na przykład w niektórych przypadkach przez zgodę aplikację ponownie — wartość nie będzie dostępna dla zapisu lub odczytu.