Versionshantering | Graph API-begrepp
Gäller för: Graph API | Azure Active Directory (AD)
Det här avsnittet sammanfattas skillnaderna för Azure Active Directory (AD) Graph API-enheter och åtgärder. Du måste ange version för en åtgärd som du vill använda genom att inkludera den api-version frågesträngparametern i begäran. Begär utan en api-version parametern avvisas och returnera ett (400) felaktig förfrågan svar. Om din tjänst anrop till en äldre version av en åtgärd kan du välja att fortsätta anropar den äldre versionen eller ändra koden för att anropa en nyare version. Eventuella skillnader i funktionalitet mellan versioner beskrivs i dokumentationen för enheten som du utför anropet.
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.
Från och med Azure AD Graph API version 1.5, den api-version parametervärdet för allmän tillgänglighet (GA) versioner har angetts som ett numeriskt värde. Följande URL visar hur man frågar översta resurserna för klienten domänen contoso.com med Graph API version 1.5: https://graph.windows.net/contoso.com?api-version=1.5. För tidigare versioner av Graph API i api-version värdet på parametern har angetts som en datumsträng i följande format: ÅÅÅÅ-MM-DD. Följande URL visar hur man frågar översta resurser av samma klientorganisation med 2013-11-08-versionen av Graph-API: https://graph.windows.net/contoso.com?api-version=2013-11-08. För förhandsgranskningsfunktioner, den api-version parametervärdet anges med hjälp av strängen ”betaversionen” enligt följande: https://graph.windows.net/contoso.com?api-version=beta.
API-kontrakt, versionshantering och gör ändringar
Vi kommer versionsnumret API för ändringar delas upp i API: et för att skydda klientprogram. Vi kan välja att öka API-version för hårt ändringar för (till exempel, om vi lägger till mycket stora nya funktioner).
Så, vad som utgör en ny ändring?
- Ta bort eller byta namn på API: er eller API-parametrar
- Ändringar i beteendet för en befintlig API
- Ändringar i felkoder & kontrakt som fel
- Något som bryter principen för minsta Astonishment
Obs: lägga till nya JSON fälten svar utgör inte en ny ändring. För utvecklare som skapa sina egna klienten proxyservrar (till exempel WCF klienter) är vår vägledning ditt klientprogram ska vara beredd att ta emot egenskaper och härledda typer som inte tidigare har definierats av Graph API-tjänsten. Även om Graph API inte är ännu OData V4 kompatibla när detta skrivs, den fortfarande följer de riktlinjer som beskrivs i den modellen versionshantering avsnitt i OData V4-specifikationen.
När vi ökar den huvudsakliga versionen av API: et (till exempel från 1,5 till 2.0), vi signalering att allt stöd för befintliga klienter som använder tidigare 1.x eller tidigare versioner kommer föråldrade och stöds inte längre efter tolv månader. Finns det Microsoft Online Services Supportpolicy under produktens livscykel för mer information.
Versioner som stöds
Följande versioner har släppts för Graph API.
Version beta
Graph API-funktioner för närvarande under förhandsgranskning finns i antingen den förhandsgranskningsfunktioner avsnitt i Graph API-begrepp, eller på den Graph-teamets blogg. Funktioner i betaversionen kräver den ”api-version = beta” frågesträngparametern. När Graph API-teamet anser att en förhandsvisningsfunktion är redo för GA vi lägger till funktionen till den senaste GA-versionen (eller om den utgör en ny ändring det skulle resultera i en ökas nytt versionsnummer). Vi lämnar inga garantier att en förhandsvisningsfunktion befordras till GA.
Vi kommer att försöka undvika några viktiga förändringar för så mycket som möjligt för beta-versionen, men vi kommer inte garantera den. Klientprogram som använder betaversionen förvänta viktiga förändringar för vid olika tidpunkter. Se kompletterande användningsvillkor för Microsoft Azure-förhandsgranskningar.
Version 1.6
Det här avsnittet visas ändringarna för Graph API version 1.6.
Graph API-version 1.6 innehåller följande ändringar i funktionen:
Stöd för Azure Active Directory B2C lokalt kontoanvändare har lagts till. Detta inbegriper nya egenskaper på den användare entiteten och en ny typ av komplexa SignInName som stöd för lokalt konto logga in på Azure Active Directory B2C-klienter. Mer information om Azure Active Directory B2C finns i dokumentation för Azure Active Directory B2C.
Tillagt stöd för tjänstidentifiering av med den ServiceEndpoint entiteten och serviceEndpoints navigeringsegenskap på den programmet och ServicePrincipal entiteter.
Tillagt stöd för anpassade Apps beteende som kan anropas av förbrukar tjänster med den tillägg och KeyValue typer och tillägg egenskapen på programmet och ServicePrincipal entiteter.
Tillagt stöd för lösenord mindre autentisering med den TrustedCAsForPasswordlessAuth entiteten i CertificateAuthorityInformation typ, och trustedCAsForPasswordlessAuth egenskapen på den TenantDetail entitet.
Lägga till den changePassword åtgärd som kan anropas för att aktivera den inloggade användaren att ändra sina lösenord.
Diagram över klientversioner 2.1.x kräver Graph API version 1.6; Diagram över 2.0.x kräver Graph API 1.5-klientversioner.
Ändra
| Entitet | Ändra beskrivning |
|---|---|
| programmet | Lägga till den tillägg -egenskap som definierar beteende som en lång att tjänsten kan använda för att anropa en app i vissa sammanhang. Lägga till den serviceEndpoints navigeringsegenskap som innehåller samlingen av slutpunkter som är tillgängliga för identifiering. |
| LicenseDetail | Ny entitet som innehåller licensinformation för en användare. |
| ServiceEndpoint | Ny entitet som innehåller service discovery-information. |
| ServicePrincipal | Lägga till den tillägg -egenskap som definierar beteende som en lång att tjänsten kan använda för att anropa en app i vissa sammanhang. Lägga till den serviceEndpoints navigeringsegenskap som innehåller samlingen av slutpunkter som är tillgängliga för identifiering. |
| SubscribedSku | Lägga till den appliesTo egenskapen. |
| TenantDetail | Lägga till den trustedCAsForPasswordlessAuth -egenskap som innehåller de certifikatutfärdare som används för att verifiera certifikatkedjan när lösenordet mindre autentisering. |
| TrustedCAsForPasswordlessAuth | Ny entitet som representerar en uppsättning certifikatutfärdare för att verifiera certifikatkedjan när lösenordet mindre autentisering. |
| användare | Lägga till den creationType -egenskap som används för att ange att användaren är ett lokalt konto. Lägga till den signInNames -egenskap som innehåller samlingen av inloggningsnamn används av ett lokalt användarkonto för att logga in på en Azure Active Directory B2C-klient. Den här egenskapen har bytt namn från alternativeSignInNamesInfo i beta. Lägga till den licenseDetails navigeringsegenskap. |
Ändringar av komplex typ
| Typ | Ändra beskrivning |
|---|---|
| tillägg | Ny typ som används för att definiera anpassade beteende som en lång att tjänsten kan använda för att anropa en app i vissa sammanhang. |
| CertificateAuthorityInformation | Nya typen som representerar en certifikatutfärdare som används vid validering av certifikatkedjan när lösenordet mindre autentisering. |
| KeyValue | Ny typ som innehåller ett nyckel / värde-par som definierar en parameter som en lång att tjänsten kan använda eller anropa i ett program som anges i en tillägg. |
| ServicePlanInfo | Lägga till den appliesTo egenskapen. Lägga till den provisioningStatus egenskapen. |
| SignInName | Ny typ innehåller information om ett inloggningsnamn som kan användas av ett lokalt användarkonto för att logga in på en Azure Active Directory B2C-klient. Den här typen har bytt namn från LogonIdentifier i beta. |
Åtgärden och funktionen ändringar
| Funktion | Ändra beskrivning |
|---|---|
| changePassword | Ny åtgärd att som kan användas för att aktivera den inloggade användaren att ändra sina lösenord. |
Version 1.5
Det här avsnittet visas ändringarna för Graph API version 1.5.
Graph API-version 1.5 introduceras funktionen följande ändringar:
Namnområdet för schemat för Graph API har ändrats från Microsoft.WindowsAzure.ActiveDirectory till Microsoft.DirectoryServices. Detta påverkar alla entiteter och komplexa typer som exponeras av Graph API.
Stöd för directory-schematilläggen har lagts till. På så sätt kan du lägga till egenskaper som krävs av programmet till katalogobjekt. Följande enheter stöder schematillägg: användare, grupp, TenantDetail, enhet, programmet, och ServicePrincipal. Som stöd för directory-schemautökningar: den ExtensionProperty entiteten har lagts till, den extensionProperties navigeringsegenskap har lagts till i programmetentiteten och en ny funktion getAvailableExtensionProperties, har lagts till att returnera registrerade tilläggsegenskaper för katalogobjekt som stöds. Mer information om hur du utökar directory-schemat finns Directory-schemautökningar.
Hur behörigheter visas har ändrats och är mer nära justerad med OAuth 2.0-koncept samt med behörigheterna som sätt representeras i andra Azure-komponenter. Den behörighet entiteten har tagits bort och har ersatts med den OAuth2PermissionGrant entitet. Den här entiteten representerar delegerade behörigheter scope för OAuth 2.0 som skickas till ett anspråk med OAuth 2.0 åtkomst-token omfång. Dessutom kan den nya AppRoleAssignment entiteten representerar programmet roller som kan tilldelas användare, grupper och tjänstens huvudnamn. Två relaterade komplexa typer har också lagts till: AppRole och OAuth2Permission. Den här ändringen har ut byta namn på vissa egenskaper och lägga till andra i följande enheter: programmet, grupp, ServicePrincipal, och användare.
Den rollen entiteten har bytt namn till DirectoryRole.
Den RoleTemplate entiteten har bytt namn till DirectoryRoleTemplate.
I tabellerna nedan listas de entiteter, komplexa typer och funktioner som lagts till, ändras eller tas bort för den här versionen.
Ändra
| Entitet | Ändra beskrivning |
|---|---|
| programmet | Uppdatera den appId egenskap från Edm.Guid till Edm.String. Lägga till den appRoles -egenskap som innehåller samlingen av roller för programmet som ett program kan förklara. Rollerna kan tilldelas användare, grupper eller tjänstens huvudnamn. Lägga till den groupMembershipClaims -egenskap som är en bitmask som konfigurerar ”grupper”-anspråket utfärdat i en användare eller OAuth 2.0-åtkomsttoken som programmet förväntas. Värdena är: 0: ingen 1: säkerhetsgrupper och Azure AD-roller, 2: reserverade och 4: reserverat. Ange bitmask till 7 får alla säkerhetsgrupper, distributionsgrupper och Azure AD-roller som den inloggade användaren är medlem i. Lägga till den knownClientApplications -egenskap som innehåller en lista över program som är knutna till den här resursprogram. Medgivande till någon av kända klientprogrammen leder medgivande till resursprogram genom en kombinerad medgivande dialogrutan (visar behörighetsomfattningen för OAuth som krävs av klienten och resursen). Lägga till den oauth2AllowImplicitFlow -egenskap som anger om det här webbprogrammet kan begära OAuth2.0 implicita flödet för token. Standardvärdet är FALSKT. Lägga till den oauth2AllowUrlPathMatching -egenskap som anger om, Azure AD som en del av OAuth 2.0 token-förfrågningar, ska tillåta sökvägsmatchning för omdirigerings-URI mot programmets replyUrls. Standardvärdet är FALSKT. Lägga till den oauth2Permissions -egenskap som innehåller samlingen av behörighetsomfattningen för OAuth 2.0 som webb-API (resurs)-program visar för klientprogram. Klientprogram kan bevilja dessa behörighetsomfattningen under medgivande. Lägga till den oauth2RequiredPostResponse -egenskap som anger om, Azure AD som en del av OAuth 2.0 token-förfrågningar, ska tillåta POST-begäranden, till skillnad från GET-begäranden. Standardvärdet är FALSKT, vilket innebär att endast GET-begäranden ska tillåtas. Lägga till den requiredResourceAccess -egenskap som anger resurser som det här programmet kräver åtkomst till och uppsättning behörighetsomfattningen för OAuth och roller för programmet som krävs under var och en av dessa resurser. Den här före konfiguration av nödvändiga resursåtkomst enheter medgivande slutanvändarens upplevelse. Lägga till den extensionProperties navigeringsegenskap som innehåller egenskaper för webbtjänsttillägg som är associerade med programmet. |
| AppRoleAssignment | Ny entitet som används för att spela in när en användare eller grupp har tilldelats ett program. I det här fallet resulterar den i ett program panelen visar upp på användarens appåtkomstpanelen. Den här entiteten kan också användas för att ge ett annat (modelleras som en tjänstens huvudnamn) programåtkomst till en resursprogrammet i en viss roll. |
| Kontakta | Lägga till den sipProxyAddress -egenskap som anger röst över IP-VOIP-session inledande protocol (SIP) adress för kontakten. |
| DirectoryObject | Lägga till den deletionTimestamp -egenskap som anger den tidpunkt då ett katalogobjekt har tagits bort. Det gäller bara för de katalogobjekt som kan återställas. För närvarande är detta stöds endast för programmet. |
| DirectoryRole | Bytt namn från rollen. Lägga till den roleTemplateId egenskapen |
| DirectoryRoleTemplate | Bytt namn från RoleTemplate. |
| ExtensionProperty | Ny entitet som gör att ett program för att definiera och använder en uppsättning ytterligare egenskaper som kan läggas till katalogobjekt (användare, grupper, klient-information, enheter, program och tjänstens huvudnamn) utan att programmet som kräver ett externt dataarkiv. |
| grupp | Lägga till den onPremisesSecurityIdentifier -egenskap som innehåller lokala säkerhetsidentifierare (SID) för den grupp som synkroniserades från lokalt till molnet. Lägga till den appRoleAssignments navigeringsegenskap som pekar på en uppsättning program (tjänstens huvudnamn) som den här gruppen har tilldelats. |
| OAuth2PermissionGrant | Ny entitet som anger en OAuth2.0 delegerad behörighet omfång. Den angivna OAuth delegerad behörighet omfång kan begäras av klientprogram (via den requiredResourceAccess samling) anropar det här resursprogrammet. Ersätter den behörighet entitet som tas bort från den här versionen. |
| Behörighet | Bytt namn till OAuth2PermissionGrant. |
| Roll | Bytt namn till DirectoryRole. |
| RoleTemplate | Bytt namn till DirectoryRoleTemplate. |
| ServicePrincipal | Lägga till den appDisplayName -egenskap som anger det visningsnamn som visas av det associerade programmet. Lägga till den appRoleAssignmentRequired -egenskap som anger om en AppRoleAssignment till en användare eller grupp krävs innan Azure AD utfärdar en användare eller en åtkomst-token till programmet. Lägga till den appRoles -egenskap som innehåller programroller som exponeras av det associerade programmet. Mer information finns i appRoles egenskapsdefinition på den programmet entitet. Lägga till den oauth2Permissions -egenskap som innehåller OAuth 2.0-behörigheterna som exponeras av det associerade programmet. Mer information finns i oauth2Permisions egenskapsdefinition på den programmet entitet. Lägga till den preferredTokenSigningKeyThumbprint egenskapen. Reserverat för intern användning. Skriv eller inte annars förlitar sig på den här egenskapen. Kan tas bort i framtida versioner. Lägga till den appRoleAssignedTo navigeringsegenskap som pekar på en uppsättning program som har tilldelats tjänstens huvudnamn. Lägga till den appRoleAssignments navigeringsegenskap som pekar på vilken uppsättning av säkerhetsobjekt (användare, grupper och tjänstens huvudnamn) som är kopplade till den här tjänstens huvudnamn. Lägga till den oauth2PermissionGrants navigeringsegenskap som pekar på en uppsättning användare personifiering beviljar som är associerade med den här tjänstens huvudnamn. Ta bort den behörigheter navigeringsegenskap |
| TenantDetail | Ta bort egenskapen tenantType. |
| användare | Lägga till den onPremisesSecurityIdentifier -egenskap som innehåller lokala säkerhetsidentifierare (SID) för användaren som synkroniserades från lokalt till molnet. Lägga till den sipProxyAddress -egenskap som anger röst över IP-VOIP-session inledande protocol (SIP) postadressen för användaren. Lägga till den appRoleAssignments navigeringsegenskap som pekar på en uppsättning program (tjänstens huvudnamn) som den här användaren har tilldelats. Lägga till den oauth2PermissionGrants navigeringsegenskap som pekar på en uppsättning OAuth 2.0 användaren personifiering beviljar som är associerade med den här användaren. Ta bort den behörigheter navigeringsegenskap. |
Ändringar av komplex typ
| Typ | Ändra beskrivning |
|---|---|
| AppRole | Ny typ som anger att programmet roller som kan begäras av klientprogram anropar det här programmet eller som kan användas för att tilldela program till användare eller grupper i en av rollerna för angivet program. |
| OAuth2Permission | Nya typen som representerar en omfattning för OAuth 2.0-behörighet. Det angivna omfånget för OAuth 2.0-behörighet kan begäras av klientprogram (via den requiredResourceAccess samling) anropar det här resursprogrammet. |
| RequiredResourceAccess | Ny typ som anger en uppsättning behörighetsomfattningen för OAuth 2.0 och roller för appen under den angivna resursen som det här programmet kräver åtkomst till. |
| resourceAccess | Nya typen som representerar en behörighet som krävs för detta program. |
Åtgärden och funktionen ändringar
| Funktion | Ändra beskrivning |
|---|---|
| getAvailableExtensionProperties | Ny funktion som returnerar en fullständig lista över egenskaper för webbtjänsttillägg som har registrerats i en katalog. Egenskaper för webbtjänsttillägg kan registreras för följande enheter: användare, grupp, enhet, TenantDetail, programmet, och ServicePrincipal. |
| getMemberObjects | Ny funktion som returnerar alla de grupp och DirectoryRole objekt att en användare, kontakt, grupp eller tjänstens huvudnamn transitivt är medlem i. |
| getObjectsByObjectIds | Ny funktion som returnerar katalogobjekt som angetts i en lista med objekt-ID: N. Du kan också ange vilka resurssamlingar (användare, grupper osv.) ska genomsökas genom att ange den valfria typer parameter. |
| Återställa | Nya service-åtgärd som gör att ett program som har tagits bort återställs. |
Version 2013-11-08
Det här avsnittet visas ändringarna för Graph API version 2013-11-08.
I tabellerna nedan listas de entiteter, komplexa typer och funktioner som lagts till, ändras eller tas bort för den här versionen.
Ändra
| Entitet | Ändra beskrivning |
|---|---|
| programmet | Lägga till den ägare navigeringsegenskap som pekar på en uppsättning katalogobjekt som är ägare till programmet. Ägarna är en uppsättning icke-administratörer som har behörighet att ändra det här objektet. Ärvd från DirectoryObject. |
| DeviceConfiguration | Ny entitet som representerar konfigurationen för en enhet. |
| DirectoryObject | Lägga till den createdOnBehalfOf navigeringsegenskap som pekar till katalogen objekt som det här objektet har skapats för. Lägga till den createdObjects navigeringsegenskap som pekar på en uppsättning katalogobjekt som har skapats av det aktuella objektet. Lägga till den ägare navigeringsegenskap som pekar på en uppsättning katalogobjekt som är ägare till det aktuella objektet. Ägarna är en uppsättning icke-administratörer som har behörighet att ändra det här objektet. Lägga till den ownedObjects navigeringsegenskap som pekar på en uppsättning katalogobjekt som ägs av det aktuella objektet. Viktiga: entiteter som är härledda från DirectoryObject ärver egenskaper och kan ärva dess navigeringsegenskaper. |
| grupp | Lägga till den ägare navigeringsegenskap som pekar på en uppsättning katalogobjekt som ägare av gruppen. Ägarna är en uppsättning icke-administratörer som har behörighet att ändra det här objektet. Ärvd från DirectoryObject. |
| Roll | Lägga till den ownedObjects navigeringsegenskap som pekar på en uppsättning katalogobjekt som ägs av rollen. Ärvd från DirectoryObject. Den rollen entiteten har bytt namn till DirectoryRole från och med version 1.5. Information om rollen, se DirectoryRole. |
| ServicePrincipal | Lägga till den appOwnerTenantID egenskapen. Lägga till den autheniticationPolicy egenskapen. Reserverat för intern användning. Använd inte. Ta bort i version 1.5. Lägga till den createdObjects navigeringsegenskap som pekar på en uppsättning katalogobjekt som har skapats av tjänstens huvudnamn. Ärvd från DirectoryObject. Lägga till den ägare navigeringsegenskap som pekar på en uppsättning katalogobjekt som är ägare till tjänstens huvudnamn. Ägarna är en uppsättning icke-administratörer som har behörighet att ändra det här objektet. Ärvd från DirectoryObject. Lägga till den ownedObjects navigeringsegenskap som pekar på en uppsättning katalogobjekt som ägs av tjänstens huvudnamn. Ärvd från DirectoryObject. |
| användare | Lägga till den immutableId -egenskap som associerar en lokal Active Directory-konto till sin Azure AD-användarobjektet. Den här egenskapen måste anges när du skapar ett nytt användarkonto i diagrammet om du använder en federerad domän för användarens userPrincipalName (UPN)-egenskapen. Lägga till den userType -egenskap som är ett strängvärde som kan användas för att klassificera användartyper i din katalog, t.ex. ”medlem” och ”Gäst”. Lägga till den createdObjects navigeringsegenskap som pekar på en uppsättning katalogobjekt som har skapats av användaren. Ärvd från DirectoryObject. Lägga till den ownedObjects navigeringsegenskap som pekar på en uppsättning katalogobjekt som ägs av användaren. Ärvd från DirectoryObject. |
Ändringar av komplex typ
| Typ | Ändra beskrivning |
|---|---|
| ServicePrincipalAuthenticationPolicy | Reserverat för intern användning. Använd inte. Ta bort i version 1.5. |
Åtgärden och funktionen ändringar
| Funktion | Ändra beskrivning |
|---|---|
| assignLicense | Ny tjänsteåtgärd som uppdaterar en användare med en lista över licenser för att lägga till eller ta bort. |
Version 2013-04-05
Detta är den grundläggande versionen av Graph API.