Directory-schemautökningar | Graph API-begrepp

Artikel
01/26/2016

Det här avsnittet beskrivs katalogtillägg i Azure AD Graph API som kan användas för att lägga till egenskaper till katalogobjekt utan ett externt dataarkiv. Till exempel om en organisation har en rad för business (LOB)-program som kräver en Skype-Id för varje användare i katalogen, kan Graph API användas för att registrera en ny egenskap med namnet skypeId för katalogobjekt användare och sedan skriva ett värde till den nya egenskapen för en viss användare. Det här avsnittet hjälper dig att förstå begränsningar i katalogtillägg, hur de är registrerade i en katalog och innehåller exempel på hur de används i Graph API.

Viktigt

Vi rekommenderar starkt att du använder Microsoft Graph i stället för Azure AD Graph API för att komma åt resurser i Azure Active Directory. Vårt utvecklingsarbete är nu samlade på Microsoft Graph och inga fler förbättringar som planeras att Azure AD Graph API. Det finns ett begränsat antal scenarier som Azure AD Graph API kan fortfarande vara lämplig. Mer information finns i Microsoft Graph eller Azure AD Graph blogginlägget i Office Dev Center.

Tillägget datatyper

Tillägg kan endast registreras med hjälp av Graph API version 1.5 eller senare. Följande egenskapstyper av kan registreras:

Egenskapstypen	Anmärkningar
Binär	maximalt 256 byte.
Boolesk
Datum och tid	Måste anges i ISO 8601-format. Kommer att lagras i UTC.
Heltal	32-bitars värde.
LargeInteger	64-bitars värde.
Sträng	högst 256 tecken.

Egenskapstyperna ovan kan registreras på följande objekt i en katalog:

Förstå hur ett tillägg är registrerad

Det är viktigt att förstå hur en tilläggsegenskapen är registrerad i en katalog och hur Azure Annonsens medgivande modellen påverkar dess registrering. Mer information om ditt medgivande program i Azure AD finns översikt av Framework medgivande i integrera program med Azure Active Directory.

Egenskaper för webbtjänsttillägg som är registrerade på en programmet objekt i utvecklarens katalog. När programmet har samtyckt till av en användare eller administratör i utvecklarens directory, egenskapen har lagts till i katalogen måltypen och blir omedelbart tillgänglig i utvecklarens directory. För ett program med flera innehavare, när programmet beviljas godkännande av en användare eller administratör i en annan organisation bli egenskaper för webbtjänsttillägg omedelbart tillgängligt på directory måltypen i den andra organisationen directory.

Om en organisation samtycker till ”skrivskyddad” behörigheten för ett program med registrerade filnamnstillägg egenskaperna fortfarande blir tillgänglig i den andra organisationen directory. Dessutom kan egenskaper för webbtjänsttillägg användas av alla tilllåten program i en organisation, inte bara för program som de har registrerats. Andra tilllåten program i den organisationen kan läsa eller skriva värden för egenskapen extension om de har tillräcklig behörighet.

Om programmet har tagits bort eller samtycke har tagits bort i den andra organisationen directory, blir den utökade egenskapen oåtkomlig directory målobjektet. Om tillägget tas bort av programmet kan också blir tillgänglig för katalogobjekt målet. Om ett program med flera innehavare lägger till ytterligare tilläggsegenskaper efter medgivande beviljats, blir de här egenskaperna omedelbart tillgänglig i den andra organisationen directory.

Obs: om en tilläggsegenskapen värdet på ett objekt och egenskapen blir tillgänglig i objektets directory egenskapen fortfarande räknas av mot det objektet högst 100 egenskapsvärden för tillägget. Det enda sättet att ta bort egenskapsvärdet från tänka på när du har angett är explicit ange det till null. Du kan göra detta om den utökade egenskapen är inte tillgänglig.

Exempelscenario

Studera följande scenario: Litware är en oberoende programvaruleverantör (ISV) som har utvecklat ett SaaS-program för andra organisationer att använda och det här programmet kräver ett tillägg egenskap med namnet skypeId för en användare -objekt. Litware först registrerar programmet i en egen katalog och sedan Graph API anropas för att registrera den utökade egenskapen på den programmet -objektet, vilket gör egenskapen åtkomligt på användarobjekt i Litware's directory. Slutligen gör Litware program med flera innehavare kan så att den kan användas i andra organisationer.

Contoso vill använda Litware's SaaS-program så att en användare eller administratör i Contoso samtycker till programmet. Programmet är registrerad i Contosos directory vid samtycke, och egenskaper för webbtjänsttillägg som har registrerats för program genom Litware omedelbart blir tillgängliga i Contoso-katalogen. Eftersom den skypeId tilläggsegenskapen för ett användarobjekt registrerades av Litware på programmet, blir tillgängligt på användaren objekt i Contosos directory. Litwares programmet eller andra tilllåten program i Contosos directory kan nu komma åt den nya egenskapen enligt de behörigheter som konfigurerats för programmet i Contosos directory. Detta innebär att program enligt deras behörigheter kan skriva ett värde för tilläggsegenskapen på en eller flera användare i katalogen. Endast användare som en skypeId värdet har skrivits returnerar egenskapen på sina användaren objekt. Detta är fallet förrän den skypeId egenskap är inställd på null, efter vilken tid användarobjektet för den aktuella användaren inte längre returnerar egenskapen.

Exempel REST-begäranden för katalogtillägg

Följande ansökningar om exemplet visar hur du registrerar, visa, skriva, läsa, filtrera och avregistrera tillägg i din katalog. Ersätt den <applicationObjectId> med registrerade programmet objekt-ID. Du kan få det här värdet på följande sätt:

Gå till https://graphexplorer.cloudapp.net/, klicka på den logga In länkar i det övre högra hörnet och logga sedan in med autentiseringsuppgifterna för ett administratörskontot i din organisations katalog.
När du har loggat in, klicka på Webbadressen i textrutan resurs (bredvid den hämta knapp) och välj den URL som slutar i program, eller klicka på hämta eller klicka på den ange nyckel.
Hitta posten för önskat program från resultaten och kopierar sedan dess objectId värde, till exempel följande: ”objectId”: ”269fc2f7-6420-4ea4-be90-9e1f93a87a64”

I det här avsnittet finns exempel begäranden för följande åtgärder:

Registrera ett tillägg
Visa registrerade tillägg
Skriva ett värde för tillägg
Ta bort värdet för ett tillägg
Att läsa värdet för ett tillägg
Filtervärde tillägg
Avregistrera ett tillägg

Fullständig exempel som använder tilläggsegenskaper finns i följande exempel i Azure AD-exemplen på Github:

WebApp-GraphAPI-DirectoryExtensions-PHP: Visar hur du skapar och använder tillägg med PHP.
WebApp-GraphAPI-DirectoryExtensions-DotNet: Visar ett organisationsschema för AAD-klient och kan läsa tillägget värden direkt ur lådan.

Registrera ett tillägg

Följande exempelbegäran skapar en extensionProperty på den önskade programmet objekt.

Format för förfrågan

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

Exempel på begäran

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

Om åtgärden lyckades, returneras en statuskod HTTP 201 skapas tillsammans med det fullständigt kvalificerade egenskapsnamn, som kan användas för att skriva värden till måltypen.

Exempelsvar

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

Visa registrerade tillägg

Följande exempelbegäran hämtar de tillägg som är registrerade på din programmet objekt.

Format för förfrågan

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

Exempel på begäran

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

Om åtgärden lyckades, returneras en HTTP-200 OK statuskod tillsammans med all information om varje tillägg-egenskap som registrerats på Application-objektet.

Exempelsvar

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

Skriva ett värde för tillägg

Följande exempelbegäran skriver ett värde för tillägget för den * skypeId ^ tilläggsegenskapen på en användaren objekt.

Format för förfrågan

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

{
    "<extensionPropertyName>": <value>
}

Exempel på begäran

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

Om åtgärden lyckades, returneras en HTTP 204 Nej innehåll statuskod.

Exempelsvar

HTTP/1.1 204 No Content

Om du försökte skriva överskrider gränsen på värdet 100 tillägget för objektet, returneras ett HTTP 403 Åtkomst nekas svar med felkoden ”Directory_ResourceSizeExceeded” och följande meddelande: ”storleken för objektet har överskridit gränsen. Minska antalet värden och försök igen med din begäran ”.

Ta bort värdet för ett tillägg

Följande exempelbegäran tar bort ett tillägg-värde som tidigare har angetts för den skypeId tilläggsegenskapen på en användaren objekt genom att ange värdet null.

Format för förfrågan

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

{
    "<extensionPropertyName>": null
}

Exempel på begäran

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
}

Om åtgärden lyckades, returneras en HTTP 204 Nej innehåll statuskod.

Exempelsvar

HTTP/1.1 204 No Content

Att läsa värdet för ett tillägg

Följande exempelbegäran utför en enkel GET på den användare som ska returnera standard egenskapsvärden samt nya tillägg egenskapens värde.

Format för förfrågan

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

Exempel på begäran

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

Om åtgärden lyckades, returneras en HTTP-200 OK statuskod tillsammans med det nya tillägg egenskapsvärdet (egenskaper för många användare har tagits bort från exempelsvar planeringsaspekter).

Exempelsvar

HTTP/1.1 200 OK

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

Filtervärde tillägg

Följande exempelbegäran filtrerar användarna av det angivna egenskapsvärdet.

Obs: Prefix sökningar på tillägg är begränsade till 71 tecken i strängen sökningar och 207 byte för sökningar på binära tillägg.

Format för förfrågan

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

Exempel på begäran

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

Om åtgärden lyckades, returneras ett HTTP 200 OK statuskod, tillsammans med resulterande användarobjektet.

Exempelsvar

HTTP/1.1 200 OK

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

Avregistrera ett tillägg

Följande exempelbegäran Avregistrerar en tilläggsegenskapen genom att utföra en borttagningsåtgärd på tillägget objekt-ID.

Format för förfrågan

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

Exempel på begäran

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

Om åtgärden lyckades, returneras en HTTP 204 Nej innehåll statuskod och den utökade egenskapen kommer att avregistreras på programmet.

Exempelsvar

HTTP/1.1 204 No Content

Funktionen tillägg och begränsningar

Följande beteende och begränsningar gäller för tilläggsegenskaper i en katalog:

Egenskaper för webbtjänsttillägg som registrerats för ett program blir tillgängliga i en katalog när en directory-användare eller administratör godkänner för programmet.
När en tilläggsegenskapen blir tillgängligt i en katalog, kan alla tilllåten program läsa eller skriva ett värde för tilläggsegenskapen för alla objekt för vilken egenskap gäller enligt programmets behörigheter i katalogen. Objekt som den utökade egenskapen gäller har angetts i egenskapen targetObjects.
Högst 100 tillägget egenskapsvärden kan skrivas i ett specifikt objekt i en katalog. Till exempel kan under förutsättning att inga andra tillägg egenskapsvärden har skrivits på alla användare i en katalog, om ett program skriver ett egenskapsvärde för tillägg till Användare1, sedan värden för 99 tilläggsegenskaper skrivas till Användare1 av programmet eller en annan program med rätt behörighet i katalogen; andra användare i katalogen kommer dock fortfarande att kunna ha upp till 100 tillägget egenskapsvärden som skrivs till dem.
Om ett program försöker ange ett värde för en ytterligare tilläggsegenskapen för ett objekt för vilka 100 tillägg egenskapsvärden har redan ställts, Graph API returnerar en 403 Nekad svar med felkoden ”Directory_ ResourceSizeExceeded ”och följande meddelande:” storleken för objektet har överskridit gränsen. Minska antalet värden och försök igen med din begäran ”.
Om en utvecklare Avregistrerar (raderar) blir en tilläggsegenskapen från ett program, den utökade egenskapen omedelbart tillgänglig i katalogen utvecklare och i kataloger som programmet har gett samtycke.
Om programmet har tagits bort från katalogen för utvecklare, registrerad egenskaper för alla webbtjänsttillägg för programmet omedelbart blir tillgänglig i katalogen utvecklare och kataloger som programmet har beviljats medgivande.
Om ett program med flera innehavare har beviljats medgivande i en katalog och att programmet är senare avregistreras (tas bort) från katalogen – till exempel av en administratör med hjälp av azure-hanteringsportalen--några egenskaper för webbtjänsttillägg som registrerats på programmet omedelbart blir tillgänglig i den katalogen.
Ett egenskapsvärde av tillägget måste anges explicit till null för att kunna tas bort från ett katalogobjekt. Om ett egenskapsvärde av tillägget har angetts för ett katalogobjekt och den utökade egenskapen blir tillgänglig i katalogen i fall som nämns ovan, kommer den utökade egenskapen inte längre vara synliga för det katalogobjektet. Den kommer dock fortfarande räknas av mot den 100 tillägg-egenskapen gränsen för objektet. Tills tillgängligheten för den utökade egenskapen återställas--t.ex, i vissa fall med principer för programmet igen - värdet inte är tillgänglig för läsning eller skrivning.

Ytterligare resurser

Azure AD Graph API-referens

Dela via

Directory-schemautökningar | Graph API-begrepp

Tillägget datatyper

Förstå hur ett tillägg är registrerad

Exempelscenario

Exempel REST-begäranden för katalogtillägg

Registrera ett tillägg

Format för förfrågan

Exempel på begäran

Exempelsvar

Visa registrerade tillägg

Format för förfrågan

Exempel på begäran

Exempelsvar

Skriva ett värde för tillägg

Format för förfrågan

Exempel på begäran

Exempelsvar

Ta bort värdet för ett tillägg

Format för förfrågan

Exempel på begäran

Exempelsvar

Att läsa värdet för ett tillägg

Format för förfrågan

Exempel på begäran

Exempelsvar

Filtervärde tillägg

Format för förfrågan

Exempel på begäran

Exempelsvar

Avregistrera ett tillägg

Format för förfrågan

Exempel på begäran

Exempelsvar

Funktionen tillägg och begränsningar

Ytterligare resurser

Ytterligare resurser