Overzicht van bewerkingen | Graph API-concepten

Artikel
03/24/2016

De Azure Active Directory (AD) Graph API is een compatibele 3.0 OData-service die u gebruiken kunt om te lezen en wijzigen van objecten, zoals gebruikers, groepen en contactpersonen in een tenant. Azure AD Graph API beschrijft de REST-eindpunten die u HTTP-aanvragen te verzenden om te kunnen uitvoeren van bewerkingen met behulp van de service. De volgende secties bevatten algemene informatie over het aanvragen van de indeling en wat ze kunnen verwachten in antwoorden wanneer u de Graph API om te lezen en schrijven van directory-bronnen, directory-functies of acties aanroepen of uitvoeren van query's op de map. Voor meer informatie gedetailleerde over het uitvoeren van specifieke bewerkingen directory-bronnen, raadpleegt u de juiste operations-onderwerp in de Azure AD Graph API-referentiemateriaal.

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.

De aanvraag is gelukt voor Graph API moet worden opgelost met een geldig eindpunt en worden de juiste opmaak, dat wil zeggen, eventuele vereiste headers moet bevatten en, indien nodig, een JSON-nettolading in de aanvraagtekst. De app maken van de aanvraag vergezeld gaan van een token ontvangen van Azure AD dat het probleem dat is geautoriseerd voor toegang tot de resources die zijn gericht op de aanvraag. De app moet kunnen berichten ontvangen van de Graph API worden verwerkt.

De secties in dit onderwerp krijgt u inzicht de indeling van aanvragen en -antwoorden die worden gebruikt met de Graph API.

Verificatie en autorisatie

Elke aanvraag voor Graph API moet een bearer-token dat is uitgegeven door Azure Active Directory die gekoppeld zijn. De token uitvoert informatie over uw app, de aangemelde gebruiker (in het geval van gedelegeerde machtigingen), verificatie en de bewerkingen op de map die uw app is gemachtigd om uit te voeren. Dit token wordt uitgevoerd in de autorisatie koptekst van de aanvraag. (Het token is ingekort als beknopt alternatief bevat) bijvoorbeeld:

Authorization: Bearer eyJ0eX ... FWSXfwtQ

De Graph API uitvoert autorisatie op basis van OAuth 2.0-machtigingsbereiken aanwezig in het token. Zie voor meer informatie over de machtigingsbereiken die de Graph API beschrijft Graph API-Machtigingsbereiken.

In de volgorde voor uw app om te verifiëren met Azure AD en de Graph-API aanroepen, moet u toe te voegen aan uw tenant en configureer deze machtigingen (OAuth 2.0-machtigingsbereiken) dat is vereist voor Windows Azure Active Directory. Zie voor meer informatie over het toevoegen en configureren van een app toepassingen integreren met Azure Active Directory.

Azure AD gebruikt de OAuth 2.0-verificatieprotocol. U kunt meer informatie over het OAuth 2.0 in Azure AD, met inbegrip van ondersteunde stromen en toegang tot tokens in OAuth 2.0 in Azure AD.

Eindpunt adressering

Om bewerkingen te voeren met de Graph API, u HTTP-aanvragen verzenden met een ondersteunde methode - doorgaans ophalen, POST, PATCH, plaatsen of--naar een eindpunt dat gericht is op de service, een resourceverzameling, een afzonderlijke resource, een navigatie-eigenschap van een bron verwijderen of een de functie of de actie beschikbaar is gemaakt door de service. Eindpunten worden uitgedrukt als URL's.

Hier volgen de basisindeling van een Graph API-eindpunt:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

De volgende onderdelen omvat de URL:

Service Root: de basis-service voor alle aanvragen voor Graph API is https://graph.windows.net.
Tenant-id {tenant_id}: de id voor de tenant die de aanvraag-doelen.
Bronpad {resource_path}: het pad naar de resource--bijvoorbeeld een gebruiker of een groep--die de aanvraag-doelen.
Graph API-versie {api_version}: de versie van de Graph API waarop de aanvraag is gericht. Dit wordt uitgedrukt als een queryparameter en is vereist.

Opmerking: In sommige gevallen kan bij het lezen van de resource-verzamelingen, OData-query-parameters kunnen worden toegevoegd aan het verzoek om te filteren, sorteren en de resulterende set pagina. Zie voor meer informatie de OData-queryparameters in dit onderwerp.

Tenant identifier {tenant_id}

U kunt de tenant van het doel van een aanvraag opgeven in een van de vier manieren:

Object-ID door tenant. De GUID die is toegewezen toen de tenant is gemaakt. Dit vindt u in de objectId eigenschap van de TenantDetail object. De volgende URL laat zien hoe het adres van de verzameling gebruikers resources met behulp van de tenant-object-ID:
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.
Door geverifieerd (geregistreerde) domeinnaam. Een van de domeinnamen die zijn geregistreerd voor de tenant. Deze kunnen worden gevonden in de verifiedDomains eigenschap van de TenantDetail object. De volgende URL laat zien hoe de verzameling gebruikers resources van een tenant met het domein contoso.com adres:
https://graph.windows.net/contoso.com/users?api-version=1.6.
Met behulp van de myOrganization alias. Deze alias is alleen beschikbaar wanneer het via OAuth Authorization Code Grant type (3-legged) verificatie. dat wil zeggen, wanneer u een scope gedelegeerde machtigingen. De alias is niet hoofdlettergevoelig. Het object-ID of tenant domein in de URL wordt vervangen. Wanneer de alias wordt gebruikt, is de tenant door Graph API afgeleid van de claims die zijn gepresenteerd in het token dat is gekoppeld aan de aanvraag. De volgende URL ziet u hoe voor het oplossen van de verzameling gebruikers resources van een tenant met behulp van deze alias:
https://graph.windows.net/myorganization/users?api-version=1.6.
Met behulp van de me alias. Deze alias is alleen beschikbaar wanneer het via OAuth Authorization Code Grant type (3-legged) verificatie. dat wil zeggen, wanneer u een scope gedelegeerde machtigingen. De alias is niet hoofdlettergevoelig. Het object-ID of tenant domein in de URL wordt vervangen. Wanneer de alias wordt gebruikt, is de gebruiker in Graph API afgeleid van de claims die zijn gepresenteerd in het token dat is gekoppeld aan de aanvraag. De volgende URL voor het oplossen van de aangemelde gebruiker met deze alias:
https://graph.windows.net/me?api-version=1.6.

Opmerking: u me alias uitsluitend naar de doel-bewerkingen op basis van de aangemelde gebruiker. Zie voor meer informatie ondertekend in gebruiker Operations.

Bronpad {resource_path}

U geeft de {resource_path} anders, afhankelijk van of u een resourceverzameling, een afzonderlijke resource, een navigatie-eigenschap van een resource ontwikkelt, een functie of de actie beschikbaar worden gemaakt op de tenant, of een functie of de actie beschikbaar gemaakt voor een bron.

Doel	Pad	Uitleg
Service Metadata	`/$metadata`	Retourneert het metagegevensdocument van de service. Het volgende voorbeeld doelen metagegevens met contoso.com tenant: `https://graph.windows.net/contoso.com/$metadata?api-version=1.6` Opmerking: Er is geen verificatie nodig zijn om te lezen van de servicemetagegevens van de.
Resourceverzameling	`/{resource_collection}`	Een resourceverzameling, zoals gebruikers of groepen in de tenant is gericht. U kunt dit pad gebruiken om te lezen van bronnen in de verzameling en, afhankelijk van het resourcetype, een nieuwe resource maken in de tenant. In veel gevallen worden de resultatenset geretourneerd door een lees verder verbeterd door toevoeging van queryparameters om te filteren, volgorde, of de pagina van de resultaten. De Gebruikersverzameling is bedoeld voor het volgende voorbeeld: `https://graph.windows.net/myorganization/users?api-version=1.6`
Één resource	`/{resource_collection}/{resource_id}`	Is bedoeld voor een specifieke bron in een tenant, zoals een gebruiker, organisatie-contactpersoon of groep. Voor de meeste bronnen de `resource_id` is de object-ID. Sommige resources toestaan aanvullende specificaties; gebruikers kunnen bijvoorbeeld ook opgegeven door de UPN (user Principal name). Afhankelijk van de bron, kunt u dit pad om op te halen van de gedeclareerde eigenschappen van de resource, de gedeclareerde eigenschappen wijzigen of verwijderen van de resource. Het volgende voorbeeld is bedoeld voor de gebruiker john@contoso.com: `https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6`
Navigatie-eigenschap (objecten)	`/{resource_collection}/{resource_id}/{property_name}`	Een navigatie-eigenschap van een specifieke bron, zoals de manager van een gebruiker of lidmaatschap van groepen of leden van een groep is gericht. U kunt dit pad gebruiken om te retourneren van het object of de objecten waarnaar wordt verwezen door de navigatie-eigenschap van het doel. Het volgende voorbeeld is bedoeld voor de manager van john@contoso.com: `https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6` Opmerking: deze vorm van adressering is alleen beschikbaar voor leesbewerkingen.
Navigatie-eigenschap (koppelingen)	`/{resource_collection}/{resource_id}/$links/{property_name}`	Een navigatie-eigenschap van een specifieke bron, zoals de manager van een gebruiker of lidmaatschap van groepen of leden van een groep is gericht. U kunt dit formulier voor het oplossen van zowel lezen en wijzigen van een navigatie-eigenschap. Bij leesbewerkingen, worden de objecten waarnaar wordt verwezen door de eigenschap als een of meer koppelingen in de hoofdtekst van antwoord geretourneerd. Bij het schrijven, zijn de objecten worden opgegeven als een of meer koppelingen in de aanvraagtekst. Het volgende voorbeeld is bedoeld voor de eigenschap manager van john@contoso.com: `https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6`
Functies of acties die worden weergegeven op de tenant	`/{function_name}`	Is bedoeld voor een functie of de actie beschikbaar is bij de tenant. Functies en acties zijn doorgaans aangeroepen met een POST-aanvraag en kunnen een aanvraagtekst bevatten. Het volgende voorbeeld-doelen de isMemberOf functie: `https://graph.windows.net/myorganization/isMemberOf?api-version=1.6`.
Functies of acties die beschikbaar worden gesteld van een resource.	`/{resource_collection}/{resource_id}/{function_name}`	Is bedoeld voor een functie of een actie van een resource wordt weergegeven. Functies en acties zijn doorgaans aangeroepen met een POST-aanvraag en kunnen een aanvraagtekst bevatten. Het volgende voorbeeld-doelen de getMemberGroups functie: `https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6`.

Graph API-versie {api-versie}

U gebruikt de api-version queryparameter voor het doel van een specifieke versie van de Graph-API voor een bewerking. Deze parameter is vereist.

De waarde voor de api-version parameter kan bestaan uit een van de volgende:

"beta"
"1.6"
"1.5"
"2013/11/08"
"2013/04/05"

Bijvoorbeeld de volgende URL zijn bedoeld voor de Gebruikersverzameling met behulp van Graph API versie 1.6:

https://graph.windows.net/myorganization/users?api-version=1.6

Zie voor meer informatie over de versies en functionele wijzigingen tussen versies Versioning.

Parameters voor OData-query

In veel gevallen wanneer u een verzameling resources, leest kunt u filteren, sorteren en pagina van de resultatenset die door het OData-queryparameters koppelen aan uw aanvraag.

De Graph API ondersteunt de volgende parameters van de Odata-query:

$filter
$batch
$expand-
$orderby
$top
$skiptoken en de vorige pagina

Zie ondersteund query's, Filters en opties van het wisselbestand voor meer informatie over ondersteunde OData-query, parameters en hun beperkingen in de Graph API.

Aanvraag- en reactieheaders

De volgende tabel ziet veelvoorkomende HTTP-headers in aanvragen met de Graph API gebruikt. Dit is niet bedoeld om te worden uitgebreid.

Aanvraag-Header	Description
Autorisatie	Vereist. Een bearer-token dat is uitgegeven door Azure Active Directory. Zie verificatie en autorisatie in dit onderwerp voor meer informatie.
Content-Type	Vereist als aanvraagtekst aanwezig is. Het mediatype van de inhoud in de aanvraagtekst. Gebruik application/json. Parameters kunnen worden opgenomen met het mediatype zijn. Opmerking: application/atom + xml en application/xml (voor koppelingen) worden ondersteund, maar worden niet aanbevolen voor beide oogpunt van prestaties en omdat ondersteuning voor XML in een toekomstige release wordt afgeschaft.
Content-Length	Vereist als aanvraagtekst aanwezig is. De lengte van de aanvraag in bytes.

De volgende tabel ziet veelvoorkomende HTTP-headers geretourneerd in antwoorden door de Graph API. Dit is niet bedoeld om te worden uitgebreid.

Reactieheader	Description
Content-Type	Het mediatype van de inhoud in de hoofdtekst van het antwoord. De standaardwaarde is application/json. Aanvragen voor miniaturen Gebruikersfoto geretourneerd installatiekopie/jpeg standaard.
Locatie	In de antwoorden op POST-verzoeken die het maken van een nieuwe resource (object) in de map geretourneerd. De URI van de zojuist gemaakte resource bevat.
ocp-aad-diagnostics-server-name	De id voor de server die de aangevraagde bewerking wordt uitgevoerd.
ocp-aad-session-key	De sleutel die de huidige sessie met de service identificeert.

Ten minste raden we dat u als volgt voor elke aanvraag:

Meld u aan een nauwkeurige tijdstempel van de verzending van het verzoek.
Verzenden en meld u de client-request-id.
Meld u de HTTP-antwoordcode en request-id.

Informatie in deze logboeken opgeeft, helpt Microsoft oplossen van problemen wanneer u om hulp of ondersteuning vragen.

Aanvraag en -antwoord instanties

Instanties van de aanvraag voor POST, PATCH en PUT-aanvragen kunnen worden verzonden in JSON- of XML-nettoladingen. Antwoorden van de server kunnen worden geretourneerd in JSON- of XML-nettoladingen. U kunt de nettolading van de in-aanvraagtekst opgeven met behulp van de Content-Type aanvraagheader en in antwoorden met behulp van de Accept aanvraag-header.

Wij raden u aan JSON nettoladingen in aanvragen en antwoorden te gebruiken met de Graph API. Dit is zowel voor betere prestaties en omdat de XML in een toekomstige release wordt afgeschaft.

Geavanceerde functies

De voorgaande secties beschreven in de opmaak van basic aanvragen en antwoorden met de Graph API. Meer geavanceerde functies toevoegen van extra queryreeksparameters of aanmerkelijk verschilde aanvraag en antwoord-instanties dan de basisbewerkingen die eerder in dit onderwerp wordt besproken.

Deze functies:

Batch-verwerking: de Graph API biedt ondersteuning voor batchverwerking. Verzenden van aanvragen in batches, vermindert retouren naar de server, waardoor de netwerkbelasting en helpt die uw bewerkingen sneller zijn voltooid. Zie voor meer informatie over batchverwerking met de Graph API batchverwerking.
Differentiële Query: de Graph API biedt ondersteuning voor het uitvoeren van differentiële query's. Differentiële query kunt u terugkeren van wijzigingen naar specifieke entiteiten in een tenant tussen aanvragen die worden uitgegeven op verschillende tijdstippen. Deze functie wordt vaak gebruikt voor het synchroniseren van een lokaal archief met wijzigingen van de tenant. Zie voor meer informatie over differentiële query met de Graph API differentiële Query.

Aanvullende bronnen

Naslaginformatie over Azure AD Graph API

Delen via