Översikt över Operations | Graph API-begrepp
Azure Active Directory (AD) Graph API är en kompatibel 3.0 OData-tjänst som du kan använda för att läsa och ändra objekt, till exempel användare, grupper och kontakter i en klient. Azure AD Graph API exponerar REST-slutpunkter som du skickar HTTP-begäranden för att kunna utföra åtgärder med hjälp av tjänsten. Följande avsnitt innehåller allmän information om hur du formatet begäranden och vad som händer i svar när Graph API för att läsa och skriva katalogresurserna, anropa funktioner för directory eller åtgärder eller köra frågor mot katalogen. Mer detaljerad information om hur du utför specifika åtgärder directory-resurser finns i lämpliga åtgärder i den Azure AD Graph API-referens för.
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.
En lyckad begäran för Graph API måste ställas till en giltig slutpunkt och vara välformad, det vill säga den måste innehålla huvuden som krävs och, om det behövs en JSON-nyttolast i begärandetexten. Appen skickar förfrågan måste innehålla en token som tas emot från Azure AD som bevisar att den har behörighet att komma åt resurser som mål för begäran. Appen måste kunna hantera alla svar togs emot från Graph API.
Avsnitt i det här avsnittet hjälper dig att förstå formatet för begäranden och -svar som används med Graph API.
Autentisering och auktorisering
Varje begäran för Graph API måste ha en ägartoken som utfärdas av Azure Active Directory ansluten. Token utför informationen om din app, inloggad användare (vid delegerade behörigheter), autentisering och åtgärder på den katalog som din app har behörighet för att utföra. Denna token utförs i den auktorisering huvudet i begäran. Till exempel (token har minskats planeringsaspekter):
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Graph API utför auktorisering baserat på behörighetsomfattningen för OAuth 2.0 finns i token. Läs mer om behörighetsomfattningen för Graph API exponerar Behörighetsomfattningen för Graph API.
Du måste lägga till den i din klient och konfigurera det att kräva behörigheter (behörighetsomfattningen för OAuth 2.0) för Windows Azure Active Directory för din app att autentisera med Azure AD och anropa Graph API. Information om att lägga till och konfigurera en app finns integrera program med Azure Active Directory.
Azure AD använder protokollet OAuth 2.0-autentisering. Du kan lära dig mer om OAuth 2.0 i Azure AD, inklusive stöds och åtkomst till token i OAuth 2.0 i Azure AD.
Slutpunktsadressering
Om du vill utföra åtgärder med Graph API du skicka HTTP-begäranden med en metod som stöds – vanligtvis hämta, efter, korrigering, PLACERA, eller ta bort--till en slutpunkt som riktar sig till tjänsten, en resurssamling, en enskild resurs, en navigeringsegenskap av en resurs eller en funktionen eller åtgärden som exponeras av tjänsten. Slutpunkter uttrycks i URL: er.
Följande beskriver det grundläggande formatet för en slutpunkt för Graph API:
https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}
Webbadressen består av följande komponenter:
- Tjänsten rot: tjänstroten för alla begäranden för Graph API är
https://graph.windows.net. - Klient ID {tenant_id}: ID för innehavaren som mål för begäran.
- Resursens sökväg {resource_path}: sökvägen till resursen – till exempel en användare eller en grupp--som mål för begäran.
- Diagram över API-versionen {api_version}: version av Graph-API som mål för begäran. Detta uttrycks som en frågeparameter som krävs.
Obs: I vissa fall, när du läser resurssamlingar OData frågeparametrar kan läggas till begäran om att filtrera, sortera och sidan resultatmängden. Mer information finns i OData frågeparametrar i det här avsnittet.
Klient-ID {tenant_id}
Du kan ange mål-innehavare för en begäran i fyra olika sätt:
Objekt av klient-ID. GUID som tilldelades när klienten skapades. Detta kan hittas i den objectId -egenskapen för den TenantDetail objekt. Följande URL visas hur resurssamling användare med hjälp av klient-ID för objektet:
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.Kontrolleras av (registrerat) domännamn. En av de domännamn som är registrerade för klienten. Dessa återfinns i den verifiedDomains -egenskapen för den TenantDetail objekt. Följande URL visas hur resurssamling användare av en klient som har domänen contoso.com:
https://graph.windows.net/contoso.com/users?api-version=1.6.Med hjälp av den
myOrganizationalias. Det här aliaset är endast tillgängligt när med hjälp av OAuth Authorization kod Grant typ (3-ledade)-autentisering. det vill säga när du använder en delegerad behörighet omfattning. Aliaset är inte skiftlägeskänsliga. Objekt-ID eller klient domän i URL: en ersätts. När alias används härleds Graph API klienten från anspråk som presenteras i den token som är kopplad till begäran. Följande URL visas hur du adressen resurssamling användare av en klient med detta alias:
https://graph.windows.net/myorganization/users?api-version=1.6.Med hjälp av den
mealias. Det här aliaset är endast tillgängligt när med hjälp av OAuth Authorization kod Grant typ (3-ledade)-autentisering. det vill säga när du använder en delegerad behörighet omfattning. Aliaset är inte skiftlägeskänsliga. Objekt-ID eller klient domän i URL: en ersätts. När alias används härleds Graph API användaren från anspråk som presenteras i den token som är kopplad till begäran. Följande Webbadress för att åtgärda den inloggade användare som använder detta alias:https://graph.windows.net/me?api-version=1.6.
Obs: du använder me alias enbart till målet åtgärder mot den inloggade användaren. Mer information finns i signerat i användaren Operations.
Resursens sökväg {resource_path}
Du anger den {resource_path} på olika sätt beroende på om du utvecklar en resurssamling, en enskild resurs, en navigeringsegenskap av en resurs, en funktion eller åtgärd exponerad på klienten eller en funktion eller en åtgärd som visas på en resurs.
| Mål | Sökväg | Förklaring |
|---|---|---|
| Service Metadata | /$metadata |
Returnerar metadata servicedokumentet. Följande exempel mål tjänstens metadata med hjälp av contoso.com-klient: https://graph.windows.net/contoso.com/$metadata?api-version=1.6 Obs: ingen autentisering krävs för att läsa tjänstmetadata. |
| Resurssamling | /{resource_collection} |
Efter en resursmängd, till exempel användare eller grupper i klienten. Du kan använda den här sökvägen för att läsa resurser i samlingen och, beroende på resurstyp, för att skapa en ny resurs i klienten. I många fall kan en resultatmängd genom en läsning att ytterligare förfinad genom att lägga till frågeparametrar att filtrera order, eller sidan resultaten. I följande exempel riktar sig till användarsamlingen: https://graph.windows.net/myorganization/users?api-version=1.6 |
| Enskild resurs | /{resource_collection}/{resource_id} |
Riktar sig till en viss resurs i en klient, till exempel en användare, en organisations kontakt eller en grupp. För de flesta resurser i resource_id är objekt-ID. Vissa resurser tillåta ytterligare specificerare; Exempelvis kan användare anges också av användarens huvudnamn (UPN). Beroende på resursen, kan du använda den här sökvägen deklarerade egenskaper för resursen, att ändra dess deklarerade egenskaper eller ta bort resursen. I följande exempel riktar sig till användaren john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6 |
| Navigeringsegenskapen (objekt) | /{resource_collection}/{resource_id}/{property_name} |
Riktar sig till en navigeringsegenskap av en specifik resurs, till exempel en användares chef eller gruppmedlemskap eller medlemmar i en grupp. Du kan använda den här sökvägen för att returnera det eller de objekt som refereras av egenskapen target navigering. I följande exempel riktar sig till chef john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6 Obs: det här formuläret för adressering är endast tillgängligt för läsning. |
| Navigeringsegenskapen (länkar) | /{resource_collection}/{resource_id}/$links/{property_name} |
Riktar sig till en navigeringsegenskap av en specifik resurs, till exempel en användares chef eller gruppmedlemskap eller medlemmar i en grupp. Du kan använda det här formuläret för adressering att både läsa och ändra en navigeringsegenskap. Objekten som refereras av egenskapen returneras som en eller flera länkar i brödtext för svar på läsåtgärder. På skrivningar angetts objekt som som en eller flera länkar i begärandetexten. I följande exempel riktar sig till egenskapen manager för john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6 |
| Funktioner eller åtgärder som exponeras för innehavaren | /{function_name} |
Riktar sig till en funktion eller en åtgärd som visas på klienten. Funktioner och åtgärder vanligtvis anropas med en POST-begäran och kan innehålla en brödtext i begäran. Följande exempel mål i isMemberOf funktionen: https://graph.windows.net/myorganization/isMemberOf?api-version=1.6. |
| Funktioner eller åtgärder som visas på en resurs. | /{resource_collection}/{resource_id}/{function_name} |
Riktar sig till en funktion eller en åtgärd som visas på en resurs. Funktioner och åtgärder vanligtvis anropas med en POST-begäran och kan innehålla en brödtext i begäran. Följande exempel mål i getMemberGroups funktionen: https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6. |
Graph API-version {api-version}
Du använder den api-version Frågeparametern om du vill rikta en viss version av Graph API för en åtgärd. Den här parametern krävs.
Värdet för den api-version parametern kan vara något av följande:
- "beta"
- "1.6"
- "1.5"
- "2013/11/08"
- "2013/04/05"
Till exempel följande URL riktar sig till användarsamlingen med Graph API version 1.6:
https://graph.windows.net/myorganization/users?api-version=1.6
Mer information om versioner och funktionen ändringar mellan versioner finns versionshantering.
OData-frågeparametrar
I många fall när du läser en samling resurser, kan du filtrera, sortera och sidan resultatmängden genom att koppla OData frågeparametrar till din begäran.
Graph API stöder följande parametrar för Odata-frågan:
- $filter
- $batch
- $expand
- $orderby
- $top
- $skiptoken och föregående sida
Se stöds frågor, filter och växling alternativ mer information om stöds OData fråga parametrar och deras begränsningar i Graph API.
Begärande- och svarshuvuden
I följande tabell visas vanliga HTTP-rubriker som används i begäran med Graph API. Det är inte tänkt att vara omfattande.
| Huvudet i begäran | Description |
|---|---|
| Auktorisering | Krävs. En ägartoken som utfärdas av Azure Active Directory. Se autentisering och auktorisering i det här avsnittet för mer information. |
| Content-Type | Krävs om begärandetexten är tillgänglig. Medietyp för innehållet i begärandetexten. Använda application/json. Parametrar som kan ingå i medietypen. Obs: application/atom + xml och application/xml (för länkar) stöds men rekommenderas inte både av prestandaskäl och eftersom stöd för XML kommer att inaktualiseras i en framtida version. |
| Content-Length | Krävs om begärandetexten är tillgänglig. Längden på begäran i byte. |
I följande tabell visas vanliga HTTP-huvuden i svar som returnerades av Graph API. Det är inte tänkt att vara omfattande.
| Svarshuvud | Description |
|---|---|
| Content-Type | Medietyp för innehållet i brödtext för svar. Standardvärdet är application/json. Begäranden om användaren miniatyr foton returnerar bild/jpeg som standard. |
| Plats | Returnerade svar på POST-förfrågningar som skapar en ny resurs (objekt) i katalogen. Innehåller URI för den nyligen skapade resursen. |
| ocp-aad-diagnostics-server-name | Identifierare för den server som utföra den begärda åtgärden. |
| ocp-aad-session-key | Den nyckel som identifierar den aktuella sessionen med katalogtjänsten. |
Minst rekommenderar vi att du gör följande för varje begäran:
- Logga en korrekt tidsstämpeln för begäran skickas.
- Skicka och logga in på
client-request-id. - Loggar HTTP-svarskoden och
request-id.
Tillhandahåller information i dessa loggar hjälper Microsoft att felsöka problem när du be om hjälp och support.
Begäran och svar
Begäran organ för POST och korrigering PUT-begäranden skickas i JSON- eller XML-nyttolaster. Serversvar returneras i JSON- eller XML-nyttolaster. Du kan ange nyttolasten i begäran organ med hjälp av den Content-Type huvudet i begäran och svar genom att använda den Accept huvudet i begäran.
Vi rekommenderar starkt att du använder JSON-nyttolaster i begäran och svar med Graph API. Detta är både av prestandaskäl och eftersom XML kommer att inaktualiseras i en framtida version.
Avancerade funktioner
I föregående avsnitt beskrivs formatering av grundläggande begäranden och -svar med Graph API. Mer avancerade funktioner kan lägga till ytterligare fråga string-parametrar eller ha markant begäran och svar organ än de grundläggande åtgärderna som beskrivits tidigare i det här avsnittet.
Funktionerna är:
- Batch-bearbetning: Graph API: N har stöd för batchbearbetning. Skicka förfrågningar i batchar minskar sändningar till servern, vilket minskar nätverksresurser och hjälper din verksamhet slutföra snabbare. Mer information om batchbearbetning med Graph-API finns gruppbearbetning.
- Differentiella frågan: Graph API: N stöder utför differentiell frågor. Differentiella frågan kan du gå tillbaka ändringarna till specifika entiteter i en klient mellan begäranden som har utfärdats vid olika tidpunkter. Den här funktionen används ofta för att synkronisera ett lokalt Arkiv med ändringarna på klienten. Mer information om differentiell frågan med Graph-API finns differentiell frågan.