Delen via

Directory-schema-uitbreidingen | Graph API-concepten

  • Artikel

Dit onderwerp wordt besproken directory uitbreidingen in de Azure AD Graph-API die kan worden gebruikt om de eigenschappen voor directory-objecten toevoegen zonder een externe gegevensarchief. Bijvoorbeeld, als een organisatie een line-of-business (LOB)-toepassing die een Skype-Id nodig voor elke gebruiker in de map heeft, kan de Graph API worden gebruikt voor het registreren van een nieuwe eigenschap skypeId van het gebruikersobject van de map met de naam en vervolgens een waarde te schrijven naar de nieuwe eigenschap voor een specifieke gebruiker. In dit onderwerp krijgt u inzicht de beperkingen van directory-uitbreidingen, hoe ze zijn geregistreerd in een map en vindt u voorbeelden van hoe deze worden gebruikt in de Graph API.

Belangrijk

Wordt aangeraden dat u Microsoft Graph in plaats van Azure AD Graph API voor toegang tot Azure Active Directory-resources. Ontwikkeling van onze producten nu concentreren zich bij Microsoft Graph en geen verdere verbeteringen zijn gepland voor Azure AD Graph API. Er zijn een zeer beperkt aantal scenario's waarvoor Azure AD Graph API nog steeds mogelijk geschikt; Zie voor meer informatie de Microsoft Graph of de Azure AD Graph blogbericht in het Office-ontwikkelaarscentrum.

Gegevenstypen van de extensie

Extensies kunnen alleen worden geregistreerd met behulp van Graph API-versie 1.5 of hoger. De volgende typen eigenschappen kunnen worden geregistreerd:

Eigenschapstype Opmerkingen
Binair maximaal 256 bytes.
Boolean-waarde
Datum/tijd Moet worden opgegeven in de ISO 8601-notatie. Wordt opgeslagen in UTC.
Geheel getal 32-bits waarde.
LargeInteger 64-bits waarde.
Tekenreeks maximaal 256 tekens.

De bovenstaande eigenschaptypen kunnen worden geregistreerd voor de volgende objecten in een map:

Begrijpen hoe een uitbreiding is geregistreerd

Het is belangrijk om te begrijpen hoe een eigenschap extension is geregistreerd in een map en hoe Azure AD van toestemming model is van invloed op de registratie ervan. Zie voor meer informatie over de toepassing toestemming in Azure AD overzicht van het Framework toestemming in toepassingen integreren met Azure Active Directory.

Extensie-eigenschappen zijn geregistreerd op een toepassing object in de directory van de ontwikkelaar. Nadat de toepassing is wil door een gebruiker of een beheerder in de directory van de ontwikkelaar, wordt de eigenschap is toegevoegd aan het doeltype van de directory en wordt onmiddellijk toegankelijk in de directory van de ontwikkelaar. Voor een multitenant-toepassing, als de toepassing toestemming is verleend door een gebruiker of een beheerder in een andere organisatie de extensie-eigenschappen worden onmiddellijk toegankelijk is op het doeltype van de directory in de map van de andere organisatie.

Als een organisatie instemt met 'alleen-lezen' machtigingen voor een toepassing met de geregistreerde extensies, de eigenschappen wordt nog steeds niet toegankelijk in de map van de andere organisatie. Bovendien zijn uitbreidingseigenschappen toegankelijk door elke instemming toepassing in een organisatie, niet alleen voor de toepassing waaraan ze zijn geregistreerd. Andere instemming toepassingen in die organisatie kunnen lees- of -waarden schrijven voor de nieuwe eigenschap extension als ze voldoende machtigingen hebben.

Als de toepassing wordt verwijderd of toestemming wordt verwijderd in de map van de andere organisatie, wordt de eigenschap extension niet toegankelijk is op het doelobject voor de directory. Als de extensie is verwijderd door de toepassing, ook wordt deze niet toegankelijk is op het doelobject voor de directory. Als een multitenant-toepassing aanvullende uitbreidingseigenschappen toevoegt nadat toestemming heeft gekregen, worden deze eigenschappen onmiddellijk toegankelijk in de directory van de andere organisatie.

Opmerking: als de waarde van de uitbreidingseigenschap van een is ingesteld op een object en die eigenschap ontoegankelijk in de map van het object, de eigenschap nog steeds in mindering gebracht op limiet van 100 eigenschapswaarden voor uitbreiding van het object. De enige manier om de waarde van de eigenschap van overweging verwijderen nadat deze is ingesteld, is expliciet instellen op null. U kunt dit niet doen als de eigenschap extension niet toegankelijk is.

Voorbeeldscenario 's

Neem het volgende scenario: Litware is een onafhankelijke softwareleverancier (ISV) die is ontwikkeld een SaaS-toepassing voor andere organisaties te gebruiken en deze toepassing vereist een extensie-eigenschap met de naam skypeId van een gebruiker object. Litware eerst registreert u de toepassing in een eigen map en klikt u vervolgens de Graph API wordt aangeroepen voor het registreren van de eigenschap extension op de toepassing object, de eigenschap van gebruikersobjecten in de directory van Litware toegankelijk maakt. Ten slotte kunt Litware u de toepassing meerdere tenants kan zodat deze kan worden gebruikt in andere organisaties.

Contoso wil gebruiken van Litware SaaS-toepassing, zodat een gebruiker of beheerder in Contoso met de toepassing instemt. Bij toestemming te geven, de toepassing is geregistreerd in de directory van Contoso en de uitbreidingseigenschappen geregistreerd voor de toepassing door Litware onmiddellijk beschikbaar gesteld in de Contoso-directory. Aangezien de skypeId uitbreidingseigenschap voor een gebruikersobject is geregistreerd door Litware over de toepassing, wordt de eigenschap toegankelijk is op gebruiker objecten in de directory van Contoso. Van Litware toepassing of andere instemming toepassingen in Contoso directory hebben nu toegang tot de nieuwe eigenschap volgens de machtigingen die voor die toepassing in de directory van Contoso is geconfigureerd. Dit betekent dat toepassingen volgens hun machtigingen geen waarde voor die eigenschap extensie op een of meer gebruikers in de map kunnen schrijven. Alleen gebruikers waarvoor een skypeId waarde is geschreven wordt die eigenschap geretourneerd op hun gebruiker object. Is dit het geval totdat de skypeId eigenschap is ingesteld op null, na het gebruikersobject voor die gebruiker wordt niet langer de eigenschap geretourneerd.

Voorbeeld REST aanvragen voor directory-uitbreidingen

Het volgende voorbeeld-aanvragen laten zien hoe registreren, weergeven, schrijven, lezen, filteren en registratie van de uitbreidingen in uw directory. Vervang de <applicationObjectId> aanduiding voor items met uw geregistreerde toepassing Object-ID. U kunt deze waarde krijgen in de volgende manier:

  1. Ga naar https://graphexplorer.cloudapp.net/, klikt u op de aanmelden koppelen aan de rechterbovenhoek en vervolgens weer aanmelden met de referenties voor een administrator-account in de directory van uw organisatie.
  2. Nadat u zich hebt aangemeld, klikt u op de URL in het tekstvak resource (naast de ophalen knop) en selecteer de URL die in toepassingen eindigt / klikt u vervolgens op ophalen of klik op de Voer sleutel.
  3. Zoek de gewenste toepassing vermelding uit de resultaten en kopieer de objectId waarde, zoals het volgende: 'objectId': '269fc2f7-6420-4ea4-be90-9e1f93a87a64'

In deze sectie zijn er voorbeeld aanvragen voor de volgende bewerkingen:

Voor volledige voorbeelden die gebruikmaken van extensie-eigenschappen, Zie de volgende voorbeelden in de Azure AD-voorbeelden op Github:

Registreren van een uitbreiding

Hiermee maakt u het volgende voorbeeld van een aanvraag een extensionProperty op de gewenste toepassing object.

De indeling van aanvraag

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

Voorbeeld van een aanvraag

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

Als de bewerking voltooid is, wordt een statuscode HTTP 201 gemaakt samen met de naam van de eigenschap FQDN-extensie, die kan worden gebruikt om waarden te schrijven naar het doeltype geretourneerd.

Voorbeeldreactie

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

Geregistreerde extensies weergeven

Het volgende voorbeeld van een aanvraag haalt de uitbreidingen die zijn geregistreerd op uw toepassing object.

De indeling van aanvraag

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

Voorbeeld van een aanvraag

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

Als de bewerking voltooid is, wordt een HTTP 200 OK statuscode samen met de informatie over elke uitbreidingseigenschap geregistreerd voor uw toepassing-object geretourneerd.

Voorbeeldreactie

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

De waarde van een uitbreiding schrijven

Het volgende voorbeeld van een aanvraag schrijft een waarde van de uitbreiding voor de * skypeId ^ uitbreidingseigenschap op een gebruiker object.

De indeling van aanvraag

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

{
    "<extensionPropertyName>": <value>
}

Voorbeeld van een aanvraag

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

Als de bewerking voltooid is, wordt een http-204 geen inhoud statuscode geretourneerd.

Voorbeeldreactie

HTTP/1.1 204 No Content

Wordt geretourneerd als de poging tot schrijven de limiet van 100 extensie waarde voor het object overschrijdt, een reactie HTTP 403-verboden met een foutcode 'Directory_ResourceSizeExceeded' en het volgende bericht: "de grootte van het object heeft de limiet overschreden. Verminder het aantal waarden en uw aanvraag opnieuw proberen'.

De waarde van een uitbreiding verwijderen

Het volgende voorbeeld van een aanvraag Hiermee verwijdert u de waarde van een extensie dat eerder is ingesteld voor de skypeId uitbreidingseigenschap op een gebruiker object door de waarde in te stellen op null.

De indeling van aanvraag

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

{
    "<extensionPropertyName>": null
}

Voorbeeld van een aanvraag

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
}

Als de bewerking voltooid is, wordt een http-204 geen inhoud statuscode geretourneerd.

Voorbeeldreactie

HTTP/1.1 204 No Content

De waarde van een uitbreiding lezen

Het volgende voorbeeld van een aanvraag voert een eenvoudige GET-bewerking op de gebruiker die de standaard eigenschapswaarden, evenals de waarde van de nieuwe uitbreiding-eigenschap wordt geretourneerd.

De indeling van aanvraag

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

Voorbeeld van een aanvraag

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

Als de bewerking voltooid is, wordt een HTTP 200 OK statuscode samen met de nieuwe uitbreiding eigenschapswaarde (veel gebruikersgegevens zijn verwijderd uit het voorbeeldantwoord als beknopt alternatief bevat) geretourneerd.

Voorbeeldreactie

HTTP/1.1 200 OK

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

De waarde van een extensie filteren

Het volgende voorbeeld van een aanvraag filtert de gebruikers met de waarde van de opgegeven extensie-eigenschap.

Opmerking: voorvoegsel zoekopdrachten over extensies zijn beperkt tot 71 tekens tekenreeks worden doorzocht en 207 bytes bij zoekopdrachten binaire uitbreidingen.

De indeling van aanvraag

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

Voorbeeld van een aanvraag

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

Als de bewerking voltooid is, wordt er een HTTP 200 OK-statuscode, samen met het resulterende gebruikersobject worden geretourneerd.

Voorbeeldreactie

HTTP/1.1 200 OK

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

Hef de registratie van een uitbreiding

Het volgende voorbeeld van een aanvraag heft de registratie van een eigenschap extension door het uitvoeren van een DELETE-bewerking op de extensie-object-ID.

De indeling van aanvraag

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

Voorbeeld van een aanvraag

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

Als de bewerking voltooid is, wordt er een http-204 geen inhoud statuscode geretourneerd en de eigenschap extension wordt registratie van de toepassing worden verwijderd.

Voorbeeldreactie

HTTP/1.1 204 No Content

Extensie gedrag en beperkingen

Het volgende gedrag en de beperkingen van toepassing op extensie-eigenschappen in een map:

  • Extensie-eigenschappen die zijn geregistreerd voor een toepassing beschikbaar gesteld in een map wanneer een directory-gebruiker of beheerder voor de toepassing instemt.

  • Nadat een eigenschap extension weer beschikbaar is in een map is, kan elke instemming toepassing lees- of een waarde voor uitbreidingseigenschap voor een van de objecten waarvoor de eigenschap toepassing volgens de machtigingen van de toepassing in de map schrijven. De objecten waarvoor de eigenschap extension is van toepassing zijn opgegeven in de eigenschap targetObjects.

  • Maximaal 100 extensie eigenschapswaarden kan op een bepaald object in een map worden geschreven. Bijvoorbeeld, kunnen als een toepassing een eigenschapswaarde extensie naar gebruiker1 schrijft, ervan uitgaande dat er geen andere extensie eigenschapswaarden op elke gebruiker in een map is geschreven, vervolgens waarden voor 99 extensie-eigenschappen worden vastgelegd in gebruiker1 door de toepassing of een ander toepassing met de juiste machtigingen in de map; andere gebruikers in de map wordt echter nog wel worden kunnen beschikken 100 extensie eigenschapswaarden naar worden geschreven.

  • Als een toepassing probeert een waarde voor de eigenschap van een extra extensie instellen op een object voor welke 100 extensie eigenschapswaarden al zijn ingesteld, Graph API retourneert een 403-verboden antwoord met de foutcode 'Directory_ ResourceSizeExceeded' en het volgende bericht: "de grootte van het object heeft de limiet overschreden. Verminder het aantal waarden en uw aanvraag opnieuw proberen'.

  • Als een ontwikkelaar deregistreren (verwijderen) wordt een extensie-eigenschap van een toepassing, wordt die eigenschap extensie onmiddellijk niet toegankelijk in de map developer en ook in mappen waarvoor de toepassing toestemming heeft gekregen.

  • Als de toepassing wordt verwijderd uit de directory developer, worden alle uitbreidingseigenschappen geregistreerd bij die toepassing onmiddellijk ontoegankelijk worden in de map ontwikkelaars en in mappen waarin de toepassing toestemming heeft gekregen.

  • Als een multitenant-toepassing heeft gekregen toestemming in een map en de toepassing wordt later (verwijderd) van die directory--bijvoorbeeld door een beheerder met de azure-beheerportal-- wordt uitbreidingseigenschappen zijn geregistreerd bij de registratie Deze toepassing onmiddellijk ontoegankelijk in die map.

  • De waarde van een extensie-eigenschap moet expliciet worden ingesteld op null om te worden verwijderd uit een directory-object. Als een eigenschapswaarde van extensie is ingesteld op een directory-object en die ontoegankelijk uitbreidingseigenschap in de map voor de redenen die hierboven, kan de eigenschap extension wordt niet meer worden zichtbaar zijn op dat directoryobject. Het wordt echter nog steeds in mindering gebracht op de limiet van 100-extensie de eigenschap waarde voor dat object. Totdat de beschikbaarheid van de eigenschap extension is hersteld--bijvoorbeeld in sommige gevallen door ermee akkoord dat de toepassing opnieuw--de waarde niet meer toegankelijk voor lezen of schrijven.

Aanvullende bronnen