Directory şema uzantıları | Grafik API'si kavramları
Bu konuda, dış veri deposuna gerek kalmadan dizin nesnelere özellikleri eklemek için kullanılan Azure AD Graph API dizin uzantıları anlatılmaktadır. Bir kuruluşta bir dizinde her kullanıcı için bir Skype kimliği gerektiren iş hattı (LOB) uygulaması varsa, örneğin, grafik API'si dizinin kullanıcı nesnesi üzerinde skypeId adlı yeni bir özellik kaydetmek ve yeni özellik için bir değer yazmak için kullanılabilir belirli bir kullanıcı. Bu konu, dizin uzantıları sınırlamaları anlamanıza yardımcı olacaktır nasıl bir dizinde kayıtlı ve bunların grafik API'sini nasıl kullanıldığı örnekler sağlar.
Önemli
Kullanmanız önerilir Microsoft Graph Azure Active Directory kaynaklara erişmek için Azure AD Graph API yerine. Geliştirme çalışmalarımızı artık Microsoft Graph yoğunlaşmıştır ve herhangi bir geliştirme için Azure AD Graph API planlanmaktadır. Senaryolar için Azure AD Graph API hala uygun olabilir, çok sınırlı sayıda vardır; Daha fazla bilgi için bkz: Microsoft Graph veya Azure AD grafik Office Geliştirici Merkezi blog postasına.
Uzantı veri türleri
Uzantıları yalnızca grafik API'si 1.5 veya daha yeni bir sürümü kullanılarak kaydedilebilir. Aşağıdaki özellik türleri kaydedilebilir:
| Özellik türü | Açıklamalar |
|---|---|
| İkili | en fazla 256 bayt. |
| Boole değeri | |
| DateTime | ISO 8601 biçiminde belirtilmelidir. UTC biçiminde depolanır. |
| Tamsayı | 32-bit değeri. |
| LargeInteger | 64-bit değeri. |
| Dize | en fazla 256 karakter. |
Yukarıdaki özellik türleri, bir dizinde aşağıdaki nesneler üzerinde kaydedilebilir:
Bir uzantı nasıl kayıtlı anlama
Uzantı özelliği bir dizine nasıl kayıtlı anlamak önemlidir ve nasıl Azure AD'ın onay modeli kayıt etkiler. Azure AD'de uygulama onayı hakkında daha fazla bilgi için bkz: onayı Framework'e Genel Bakış içinde Azure Active Directory Tümleştirme uygulamalarla.
Üzerinde kayıtlı uzantısı özellikleri bir uygulama nesnesi Geliştirici dizin içinde. Uygulama bir kullanıcı veya geliştiricinin dizininde bir yönetici tarafından seçtiği sonra özelliği hedef dizin türü eklenir ve geliştirici dizininde hemen erişilebilir olur. Uygulama bir kullanıcı veya başka bir kuruluştaki bir yönetici tarafından izin verildiğinde bir çok kiracılı uygulama için uzantısı özellikleri hemen hedef dizin türü diğer kuruluşun dizininde erişilebilir olur.
"Salt okunur olarak" Kuruluş izin verirse kayıtlı uzantılı bir uygulama için izinler, özelliklerin hala hale gelir diğer kuruluşun dizininde erişilebilir. Ayrıca, uzantısı özellikleri yalnızca kayıtlı uygulama için bir kuruluşta razı herhangi bir uygulama tarafından erişilebilir. Belirli bir kuruluş razı diğer uygulamalarda okuma veya yeterli izinlere sahip yeni uzantı özelliği için değerler yazma.
Uzantı özelliği uygulama silinmiş veya onay diğer kuruluşun dizininde kaldırılır, hedef dizin nesnesinde erişilemez duruma gelir. Uzantısı uygulama tarafından silinirse, aynı zamanda hedef dizin nesnesinde erişilemezse. İzin verildi sonra çok kiracılı uygulama ek uzantısı özellikleri eklerse, bu özellikler diğer kuruluşun dizininde hemen erişilebilir olur.
Not: bir uzantı özelliğinin değeri bir nesne üzerinde ayarlanmış ve bu özellik bu nesnenin dizininde erişilemez duruma, özellik hala 100 uzantı özelliği değeri, nesnenin sınırınızı sayar. Ayarlandıktan sonra göz önünde bulundurarak özellik değerini Kaldır yalnızca açıkça null olarak ayarlamak için yoludur. Uzantı özelliği erişilebilir değilse bu işlemi yapamazsınız.
Örnek senaryo
Aşağıdaki senaryoyu düşünün: Lıtware diğer kuruluşlara için bir SaaS uygulaması geliştirmiştir bir bağımsız yazılım satıcısı (ISV) ve bu uygulamayı adlı bir uzantı özelliği gerektirir skypeId bir kullanıcı nesne. Lıtware ilk uygulama, kendi dizininde kaydeder ve grafik API'si üzerinde uzantı özelliği kaydettirmek için daha sonra çağrılır uygulama özelliği Lıtware 's dizinindeki kullanıcı nesnelerinde erişilebilir kılar nesnesi. Diğer kuruluşta kullanılabilir son olarak, Lıtware uygulama çok kiracılı yeteneği sağlar.
Contoso Lıtware 's SaaS uygulamasına kullandığından, bir kullanıcının veya yöneticinin contoso'da uygulama için izin istiyor. Onay, bağlı uygulama Contoso dizininde kaydedilir ve uygulama tarafından hemen Contoso dizininde kullanılabilir hale gelir Lıtware uzantısı özellikleri kayıtlı. Bu yana skypeId uzantı özelliği için bir kullanıcı nesnesi üzerinde uygulama tarafından Lıtware kaydedildi, özellik üzerinde erişilebilir hale kullanıcı Contoso directory içindeki nesneleri. Şimdi Lıtware 's uygulama veya Contoso directory razı diğer uygulamalarda Contoso dizininde bu uygulama için yapılandırılan izinler göre yeni özellik erişebilir. Bu uygulamalar, onların izinlerini göre dizininde bir veya daha fazla kullanıcıları bu uzantı özelliği için bir değer yazabilir anlamına gelir. Yalnızca kullanıcıların kendisi için bir skypeId değeri döndürür o özelliğin üzerine yazıldı kendi kullanıcı nesnesi. Bu durumda kadar olacaktır skypeId özelliği ayarlanmış null, o kullanıcının artık özelliği döndürür için hangi kullanıcı nesnesi saat sonra.
Örnek REST istekleri dizin uzantıları için
Aşağıdaki örnek isteklerini kaydetme, görüntülemek, yazma, okuma, filtre ve dizininizde uzantıları kaydı gösterilmektedir. Değiştir <applicationObjectId> kayıtlı uygulamanızın nesne kimliğiyle yer tutucusu Bu değer aşağıdaki yolla alabilirsiniz:
- Git https://graphexplorer.cloudapp.net/, tıklatın oturum bağlantı sağ üst köşede ve ardından kuruluşunuzun dizinindeki yönetici hesabı için kimlik bilgilerini kullanarak oturum açın.
- Oturum açtıktan sonra kaynak metin kutusu bölümünde URL'yi tıklatın (yanına almak düğmesi) ve uygulamalarda bitip URL'yi seçin / ardından almak veya'ı tıklatın girin anahtar.
- Sonuçlarından istenen uygulama girişini bulun ve ardından kopyalama kendi objectID aşağıdaki gibi değer: "objectID": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"
Bu bölümde, aşağıdaki işlemleri için örnek istekleri vardır:
- Uzantı kaydetme
- Kayıtlı uzantıları görüntüleyin
- Bir uzantı değerini Yaz
- Bir uzantı değerini Kaldır
- Bir uzantı değer okuma
- Filtre bir uzantı değeri
- Uzantı kaydı
Uzantısı özellikleri kullanmak tam örnekleri için Github'da Azure AD örnekleri aşağıdaki örneklerde bakın:
- WebApp GraphAPI DirectoryExtensions PHP: ile PHP uzantıları oluşturulacağı ve kullanılacağı gösterilmektedir.
- WebApp GraphAPI DirectoryExtensions DotNet: bir AAD kiracısı Kuruluş Şeması görüntüler ve kutunun sağ dışında uzantısı okumanızı sağlar.
Uzantı kaydetme
Aşağıdaki örnek isteği oluşturur bir extensionProperty istenen üzerinde uygulama nesnesi.
İstek biçimi
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>"
]
}
Örnek istek
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"
]
}
İşlem başarılı olduysa, bir hedef türü değerleri yazmak için kullanılan tam uzantı özelliği adı ile birlikte HTTP 201 oluşturulan durum kodu döndürür.
Örnek yanıt
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"
]
}
Kayıtlı uzantıları görüntüleyin
Aşağıdaki örnek istek üzerinde kayıtlı uzantıları alır, uygulama nesnesi.
İstek biçimi
GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1
Örnek istek
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
İşlem başarılı olduysa, uygulama nesnesi üzerinde kayıtlı her bir uzantı özellik ilgili tüm bilgileri ile birlikte bir HTTP 200 Tamam durum kodu döndürür.
Örnek yanıt
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"
]
}
]
}
Bir uzantı değerini Yaz
Aşağıdaki örnek isteği için bir uzantı değer yazar * skypeId ^ uzantısı özelliği bir kullanıcı nesnesi.
İstek biçimi
PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
{
"<extensionPropertyName>": <value>
}
Örnek istek
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"
}
İşlem başarılı olduysa, bir HTTP 204 Hayır içerik durum kodu döndürür.
Örnek yanıt
HTTP/1.1 204 No Content
Denenen yazma nesnesi için 100 uzantısı değer sınırı değerini geçiyor varsa bir hata kodu "Directory_ResourceSizeExceeded" ve aşağıdaki ileti ile HTTP 403 Yasak bir yanıt döndürür: "nesnenin boyutu sınırını aştı. Lütfen değerlerin sayısını azaltın ve isteğinizi yeniden deneyin".
Bir uzantı değerini Kaldır
Aşağıdaki örnek istek için önceden ayarlanmış bir uzantı değeri kaldırır skypeId uzantısı özelliği bir kullanıcı değeri ayarlayarak nesne null.
İstek biçimi
PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
{
"<extensionPropertyName>": null
}
Örnek istek
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
}
İşlem başarılı olduysa, bir HTTP 204 Hayır içerik durum kodu döndürür.
Örnek yanıt
HTTP/1.1 204 No Content
Bir uzantı değer okuma
Aşağıdaki örnek istek standart özellik değerlerinin yanı sıra yeni uzantı özelliği değeri dönecektir kullanıcının basit bir alma işlemi gerçekleştirir.
İstek biçimi
GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Örnek istek
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
İşlem başarılı ise (birçok kullanıcı özelliklerini kısaltma örnek yanıt kaldırılmıştır) yeni uzantı özellik değeri ile birlikte bir HTTP 200 Tamam durum kodu döndürür.
Örnek yanıt
HTTP/1.1 200 OK
{
...
"usageLocation": null,
"userPrincipalName": "Jim@contoso.onmicrosoft.com",
"userType": "Member"
"extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}
Filtre bir uzantı değeri
Aşağıdaki örnek istek kullanıcı tarafından belirtilen uzantı özellik değeri filtreler.
Not: uzantıları önek aramaları 71 karakter dizesi aramalar ve ikili uzantıları aramaları için 207 bayt ile sınırlı.
İstek biçimi
GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1
Örnek istek
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
İşlem başarılı olduysa, sonuçta elde edilen kullanıcı nesnesi ile birlikte bir HTTP 200 Tamam durum kodu döndürür.
Örnek yanıt
HTTP/1.1 200 OK
{
...
"usageLocation": null,
"userPrincipalName": "Jim@contoso.onmicrosoft.com",
"userType": "Member"
"extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}
Uzantı kaydı
Aşağıdaki örnek istek uzantısı nesne kimliği üzerinde bir silme işlemi gerçekleştirerek bir uzantı özelliği kaydını siler
İstek biçimi
DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1
Örnek istek
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
İşlem başarılı olduysa, bir HTTP 204 Hayır içerik durum kodu döndürür ve uzantı özelliği uygulamanın kaydı.
Örnek yanıt
HTTP/1.1 204 No Content
Uzantısı davranışı ve sınırlamalar
Bir dizindeki uzantısı özellikleri için aşağıdaki davranışı ve sınırlamalar uygulanır:
Uygulama için bir dizin kullanıcı veya yönetici izin, bir uygulama için kayıtlı uzantısı özellikleri bir dizinde kullanılabilir olur.
Uzantı özelliği bir dizinde kullanılabilir hale geldikten sonra herhangi bir razı uygulama okuma veya herhangi biri için hangi nesneleri için dizinde uygulamanın izinleriyle özelliği uygulanır, uzantı özelliği için bir değer yazma. Uzantı Özelliği uygulandığı nesneleri targetObjects özelliğinde belirtilir.
En fazla 100 uzantısı özellik değerleri, bir dizindeki belirli bir nesne üzerinde yazılabilir. Örneğin, bir uygulama bir uzantı özelliği değeri user1 yazıyorsa üzerinde herhangi bir kullanıcı bir dizindeki başka bir uzantı özellik değerlerini yazılan varsayıldığında, ardından 99 uzantısı özellikleri için değerleri user1, uygulama veya başka bir yazılabilir uygulama dizinindeki uygun izinlere sahip; Ancak, diğer kullanıcıların dizindeki hala yazılmış 100 uzantısı özellik değerlerini zorunda mümkün olacaktır.
Bir uygulama bir ek uzantı özelliği için bir değer 100 hangi uzantısı için özellik değerlerini zaten ayarlanmış bir nesne üzerinde ayarlanmış çalışırsa, grafik API'si döndürür bir 403 Yasak "Directory_ hata kodunu Yanıtla ResourceSizeExceeded"ve aşağıdaki ileti:"nesnenin boyutu sınırını aştı. Lütfen değerlerin sayısını azaltın ve isteğinizi yeniden deneyin".
Bir geliştirici kaydını kaldırır (siler) bir uygulama, o uzantı özelliği hemen uzantısı özelliğinden Geliştirici dizin hem de onay uygulama verildi dizinleri erişilemez haline gelir.
Uygulama geliştiricisi dizinden kaldırılırsa, hemen Geliştirici dizini ve bu uygulamaya izin verildi dizinleri erişilemez hale bu uygulama için tüm uzantısı özellikleri kayıtlı.
Bir dizindeki izin verilmiş bir çok kiracılı uygulama ve uygulamanın daha sonra olduğunu (kaldırılan) dizininden bu--örneğin, azure Yönetim Portalı--kayıtlı tüm uzantısı özellikleri kullanılarak bir yönetici tarafından kaydı Bu uygulama hemen bu dizinde erişilemez hale gelir.
Bir uzantı özelliği değeri açıkça ayarlanmalıdır null bir dizin nesneden kaldırılması için. Bir uzantı özelliği değeri bir dizin nesnesi üzerinde ayarlanır ve uzantı özelliği için yukarıdaki bildirdi nedenlerden biriyle dizinde erişilemezse, ardından uzantı özelliği artık dizin nesnede görünür. Bu ancak, yine söz konusu nesne için 100 uzantı özelliği değeri sınırı karşı sayar. Uzantı özelliği kullanılabilirliğini--Örneğin, bazı durumlarda, uygulamayı yeniden onaylıyorsunuz tarafından geri--değer okuma veya yazma için erişilemeyecek kadar.