Rozšíření schématu adresáře | Rozhraní Graph API koncepty

Článek
01/26/2016

Toto téma popisuje rozšíření adresáře v Azure AD Graph API, který můžete použít k přidání vlastností do adresáře objekty bez nutnosti externím úložišti. Například pokud organizace má řádek obchodní (LOB) aplikace, která vyžaduje Skype Id pro každého uživatele v adresáři, rozhraní Graph API lze použít k registraci novou vlastnost s názvem skypeId na objekt uživatele adresáři a pak zapsat hodnotu do nové vlastnosti pro konkrétního uživatele. Toto téma vám pomůže porozumět omezení rozšíření adresáře, jak by se zaregistrovány v adresáři a zadejte příklady, jak se používají v rozhraní Graph API.

Důležité

Důrazně doporučujeme použít Microsoft Graph místo Azure AD Graph API pro přístup k prostředkům Azure Active Directory. Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API. Je velmi omezený počet scénářů, pro které Azure AD Graph API může být vhodné; Další informace najdete v tématu Microsoft Graph nebo Azure AD Graph příspěvku na blogu v Office Dev Center.

Rozšíření datových typů

Rozšíření se dají registrovat jenom pomocí rozhraní Graph API verze 1.5 nebo novější. Následující typy vlastností se dají registrovat:

Typ vlastnosti	Poznámky
Binární	maximální 256 bajtů.
Logická hodnota
Data a času	Je třeba zadat ve formátu ISO 8601. Uloží ve standardu UTC.
Celé číslo	32bitová hodnota.
LargeInteger	hodnota 64-bit.
Řetězec	maximálně 256 znaků.

Typy vlastností výše můžete zaregistrovat na následující objekty v adresáři:

Pochopení, jak je zaregistrováno rozšíření

Je důležité pochopit, jak je zaregistrován ve vlastnosti rozšíření v adresáři a jak Azure AD na souhlasu modelu ovlivňuje jeho registraci. Další informace o souhlasu aplikace ve službě Azure AD najdete v tématu přehled rozhraní souhlas v integrace aplikací s Azure Active Directory.

Vlastnosti rozšíření jsou registrované na aplikace objektu v adresáři pro vývojáře. Po aplikaci byl souhlasí s uživatelem nebo správcem v adresáři pro vývojáře, vlastnost se přidá na cílový typ. adresáře a bude okamžitě dostupný v adresáři pro vývojáře. Aplikace pomocí víceklientské aplikace při udělení souhlasu uživatele nebo správce v jiné organizaci, vlastnosti rozšíření stát okamžitě dostupné na cílový typ adresáře v adresáři jiné organizace.

Pokud organizace souhlasí s "jen pro čtení" oprávnění pro aplikace s registrované přípony vlastnosti stále bude dostupný v adresáři jiné organizace. Kromě toho jsou přístupné pro všechny svolení aplikace v organizaci, ne jenom pro aplikace, do kterého jsou registrované vlastnosti rozšíření. Jiné svolení aplikace v dané organizace můžou číst nebo zapisovat hodnoty pro nové vlastnosti rozšíření, pokud mají dostatečná oprávnění.

Pokud aplikace je odstraněn nebo souhlasu je odebrán v adresáři jiné organizace, vlastnosti rozšíření nedostupné v cílovém objektu adresáře. Pokud je rozšíření odstraní aplikaci, také čitelná v cílovém objektu adresáře. Pokud víceklientské aplikace přidá další rozšíření vlastností po udělení souhlasu, stanou se okamžitě dostupné v jiné organizaci directory tyto vlastnosti.

Poznámka:: Pokud vlastnost rozšíření hodnota nastavena na objekt a tuto vlastnost k ní v adresáři tento objekt, vlastnost započítává tento objekt limit 100 hodnot vlastností rozšíření. Jediným způsobem, jak odebrat hodnotu vlastnosti brány v úvahu, jakmile byla nastavena je explicitně nastavit na hodnotu null. Nelze provést, pokud vlastnost rozšíření je nedostupná.

Příklad scénáře

Vezměte v úvahu následující scénář: Litware je nezávislý dodavatel softwaru (ISV), proto vyvinul jiné organizace, použijte aplikaci SaaS a tato aplikace vyžaduje rozšíření vlastnost s názvem skypeId na uživatele objekt. Litware nejprve zaregistruje aplikaci do vlastního adresáře, a pak se nazývá rozhraní Graph API k registraci vlastnosti rozšíření na aplikace objekt, který umožňuje vlastnost na uživatelské objekty v adresáři Litware's přístup. Nakonec Litware díky víceklientské aplikace podporující, aby se můžete použít v jiných organizacích.

Contoso chce použít Litware's aplikace SaaS, takže uživatel nebo správce ve společnosti Contoso souhlasí k aplikaci. Po souhlasu aplikace je zaregistrován v adresáři společnosti Contoso a vlastnosti rozšíření registrované pro danou aplikaci pomocí Litware okamžitě k dispozici v adresáři společnosti Contoso. Vzhledem k tomu skypeId vlastnost rozšíření pro objekt uživatele byl zaregistrován Litware na aplikaci, bude přístupný na vlastnost uživatele objekty v adresáři společnosti Contoso. Litware's aplikace nebo jiné svolení aplikace v adresáři společnosti Contoso teď mají přístup k nové vlastnosti podle oprávnění konfigurovaná pro tuto aplikaci v adresáři společnosti Contoso. To znamená, že aplikace podle jejich oprávnění může zapsat hodnotu pro tuto vlastnost rozšíření na jeden nebo více uživatelů v adresáři. Jenom uživatelé, pro který skypeId byla zapsat hodnotu, vrátí tuto vlastnost na jejich uživatele objektu. To bude v případě až skypeId je nastavena na null, po který čas objektu uživatele pro tohoto uživatele bude už vrátit vlastnost.

Ukázka REST požadavky na rozšíření adresáře

Následující ukázka požadavky ukazují, jak se zaregistrovat, zobrazení, zápisu, číst, filtrovat a zrušit rozšíření ve vašem adresáři. Nahraďte <applicationObjectId> zástupný symbol registrované aplikaci ID objektu. Tuto hodnotu můžete získat následujícím způsobem:

Přejděte na https://graphexplorer.cloudapp.net/, klikněte přihlásit odkaz v pravém horním rohu a pak se přihlaste pomocí přihlašovacích údajů pro účet správce v adresáři vaší organizace.
Po přihlášení, klikněte na adresu URL do textového pole prostředků (vedle získat tlačítko) a vyberte adresu URL, které končí v aplikacích / klikněte získat nebo klikněte na tlačítko zadejte klíč.
Vyhledejte položku požadované aplikaci z výsledků a pak zkopírujte jeho objectId hodnotu, jako jsou následující: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

V této části jsou požadavky na ukázky pro následující operace:

Registrace rozšíření
Zobrazit registrované přípony
Zapsat hodnotu rozšíření
Odebrat hodnotu rozšíření
Číst hodnotu rozšíření
Filtrovat hodnotou rozšíření
Zrušit registraci rozšíření

Pro úplnou ukázky, které používají – vlastnosti rozšíření najdete na Githubu následující ukázky ukázky Azure AD:

WebApp GraphAPI DirectoryExtensions PHP: ukazuje, jak vytvořit a použít rozšíření s PHP.
WebApp GraphAPI DirectoryExtensions DotNet: Zobrazí organizační diagram AAD klienta a umožňuje čtení hodnot rozšíření okamžitě po nasazení.

Registrace rozšíření

Vytvoří následující ukázková žádost extensionProperty na požadovanou aplikace objektu.

Formát požadavku

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>"
    ]
}

Ukázková žádost

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"
    ]
}

Pokud byla operace úspěšná, vrátí kód stavu HTTP 201 vytvořen společně s rozšíření plně kvalifikovaný název vlastnosti, které lze použít pro zápis hodnoty na typ cíle.

Ukázková odpověď

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"
    ]
}

Zobrazit registrované přípony

Následující ukázková žádost získá přípony, které jsou registrované na vaše aplikace objektu.

Formát požadavku

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

Ukázková žádost

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

Pokud byla operace úspěšná, vrátí stavový kód HTTP 200 OK společně s všechny informace o jednotlivých vlastnostech rozšíření zaregistrovat u objektu vaší aplikace.

Ukázková odpověď

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"
            ]
        }
    ]
}

Zapsat hodnotu rozšíření

Následující ukázková žádost zapíše hodnotu rozšíření pro * skypeId ^ vlastnost rozšíření na uživatele objektu.

Formát požadavku

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

{
    "<extensionPropertyName>": <value>
}

Ukázková žádost

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"
}

Pokud byla operace úspěšná, vrátí stavový kód HTTP 204 bez obsahu.

Ukázková odpověď

HTTP/1.1 204 No Content

Pokud pokus o zápis převyšuje limit hodnotu 100 rozšíření pro objekt, vrátí odpověď HTTP 403 Zakázáno s kódem chyby "Directory_ResourceSizeExceeded" a následující zpráva: "velikost objektu překročil svůj limit. Zmenšete prosím počet hodnot a opakujte žádost".

Odebrat hodnotu rozšíření

Následující ukázková žádost odebere hodnotu rozšíření, která byla dříve nastavena pro skypeId vlastnost rozšíření na uživatele objektu podle nastavení na hodnotu null.

Formát požadavku

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

{
    "<extensionPropertyName>": null
}

Ukázková žádost

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
}

Pokud byla operace úspěšná, vrátí stavový kód HTTP 204 bez obsahu.

Ukázková odpověď

HTTP/1.1 204 No Content

Číst hodnotu rozšíření

Následující ukázková žádost provede jednoduché operace GET na uživatele, který vrátí hodnoty standardní vlastností, jakož i nová hodnota vlastnosti rozšíření.

Formát požadavku

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

Ukázková žádost

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

Pokud byla operace úspěšná, vrátí stavový kód HTTP 200 OK společně s novou hodnotu vlastnosti rozšíření (mnoho vlastností uživatele byly odebrány z ukázková odpověď jako stručný výtah).

Ukázková odpověď

HTTP/1.1 200 OK

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

Filtrovat hodnotou rozšíření

Následující ukázková žádost filtruje uživatele vlastnost hodnotou zadanou příponu.

Poznámka:: Předpona hledání na rozšíření jsou omezeny na 71 znaků pro hledání řetězce a 207 bajtů pro vyhledávání na binární rozšíření.

Formát požadavku

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

Ukázková žádost

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

Pokud byla operace úspěšná, vrátí stavový kód HTTP 200 OK, společně s výsledný objekt uživatele.

Ukázková odpověď

HTTP/1.1 200 OK

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

Zrušit registraci rozšíření

Následující ukázková žádost zruší registraci ve vlastnosti rozšíření provedením operace odstranění v ID rozšíření objektu.

Formát požadavku

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

Ukázková žádost

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

Pokud byla operace úspěšná, vrátí HTTP 204 ne obsahu stavový kód a vlastnosti rozšíření se nezaregistroval v aplikaci.

Ukázková odpověď

HTTP/1.1 204 No Content

Rozšíření chování a omezení

Následující chování a omezení platí pro vlastnosti rozšíření v adresáři:

Vlastnosti rozšíření registrována pro aplikaci k dispozici v adresáři, když adresáře uživatele nebo správce souhlasí pro aplikaci.
Jakmile bude k dispozici v adresáři ve vlastnosti rozšíření, všechny svolení aplikace může čtení nebo zápisu hodnotu pro tuto vlastnost rozšíření pro všechny objekty, pro které vlastnost se vztahuje podle oprávnění tuto aplikaci v adresáři. Objekty, pro které platí vlastnost rozšíření jsou zadaná ve vlastnosti targetObjects.
Nesmí být delší než 100 hodnot vlastností rozšíření lze zapisovat na určitý objekt v adresáři. Například za předpokladu, že žádné jiné hodnoty pro vlastnost rozšíření byla zapsána na všechny uživatele v adresáři, pokud aplikace zapisuje hodnotu vlastnosti rozšíření uživatel1, pak hodnoty pro 99 ostatní vlastnosti rozšíření může lze zapisovat uživatel1 pomocí této aplikace nebo jiné aplikace s příslušnými oprávněními v adresáři; ostatní uživatelé v adresáři jsou však zůstanou mohou mít 100 hodnot vlastností rozšíření zapisovat do nich.
Pokud se aplikace pokusí nastavit hodnotu pro vlastnost další rozšíření pro objekt, pro které 100 rozšíření již byly nastaveny hodnoty vlastností, vrátí rozhraní Graph API 403 Zakázáno odpověď s kódem chyby "Directory_ ResourceSizeExceeded"a následující zpráva:"velikost objektu překročil svůj limit. Zmenšete prosím počet hodnot a opakujte žádost".
Pokud vývojář zruší registraci (odstraní) ve vlastnosti rozšíření z aplikace, okamžitě tuto vlastnost rozšíření nedostupné v adresáři developer a také v adresářích, pro které aplikace udělen souhlas.
Pokud aplikace je odebrán z adresáře, developer, všechny vlastnosti rozšíření zaregistrovat k dané aplikaci okamžitě stanou se nedostupnými v adresáři developer a adresáře, ve kterých byla udělena aplikace souhlasu.
Pokud aplikace víceklientské byla udělena souhlas v adresáři a později je aplikace neregistrovaná (odebrán) z tohoto adresáře – například správce pomocí portálu správy azure – pak všechny vlastnosti rozšíření registrovaný na tuto aplikaci, ihned stanou se nedostupnými v tomto adresáři.
Hodnotou vlastnosti rozšíření musí být explicitně nastaveny null Chcete-li odebrat z objektu adresáře. Pokud je hodnota vlastnosti rozšíření nastavena na objekt adresáře a vlastnost rozšíření stane nedostupné v adresáři z důvodů uvedených výše, pak vlastnost rozšíření se už nebude zobrazovat u tohoto objektu adresáře. Ho se, ale stále započítává limit 100 rozšíření vlastnost hodnota pro tento objekt. Dokud dostupnost vlastnost rozšíření obnoví – například v některých případech souhlas k aplikaci znovu – hodnota nebudete mít přístup pro čtení nebo zápisu.

Další zdroje informací

Odkaz na Azure AD Graph API

Sdílet prostřednictvím

Rozšíření schématu adresáře | Rozhraní Graph API koncepty

Rozšíření datových typů

Pochopení, jak je zaregistrováno rozšíření

Příklad scénáře

Ukázka REST požadavky na rozšíření adresáře

Registrace rozšíření

Formát požadavku

Ukázková žádost

Ukázková odpověď

Zobrazit registrované přípony

Formát požadavku

Ukázková žádost

Ukázková odpověď

Zapsat hodnotu rozšíření

Formát požadavku

Ukázková žádost

Ukázková odpověď

Odebrat hodnotu rozšíření

Formát požadavku

Ukázková žádost

Ukázková odpověď

Číst hodnotu rozšíření

Formát požadavku

Ukázková žádost

Ukázková odpověď

Filtrovat hodnotou rozšíření

Formát požadavku

Ukázková žádost

Ukázková odpověď

Zrušit registraci rozšíření

Formát požadavku

Ukázková žádost

Ukázková odpověď

Rozšíření chování a omezení

Další zdroje informací

Další materiály