Table of contents

Operace přehled | Rozhraní Graph API konceptyOperations overview | Graph API concepts

Jimaco Brannian|Poslední aktualizace: 19. 6. 2018
|
1 Přispěvatel

Rozhraní Graph API Azure Active Directory (AD) je služba kompatibilní OData 3.0, která můžete použít ke čtení a úpravy objektů, jako jsou uživatelé, skupiny a kontaktů v klientovi.The Azure Active Directory (AD) Graph API is an OData 3.0 compliant service that you can use to read and modify objects such as users, groups, and contacts in a tenant.Azure AD Graph API zpřístupní koncové body REST, které odešlete žádostí HTTP, abyste mohli provádět operace pomocí služby.Azure AD Graph API exposes REST endpoints that you send HTTP requests to in order to perform operations using the service.Následující části obsahují obecné informace o tom, jak formát požadavků a co mají očekávat v odpovědi při použití rozhraní Graph API číst a zapsat prostředky adresáře, volání funkce adresáře nebo akce nebo provádět dotazy na adresář.The following sections provide general information about how to format requests and what to expect in responses when you use the Graph API to read and write directory resources, call directory functions or actions, or perform queries against the directory.Podrobné informace o provádění konkrétní operace directory prostředky, naleznete v tématu příslušné operace v referenční dokumentace rozhraní API Azure AD Graph.For more detailed information about performing specific operations directory resources, see the appropriate operations topic in the Azure AD Graph API reference.

Důležité

Důrazně doporučujeme použít Microsoft Graph místo Azure AD Graph API pro přístup k prostředkům Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Je velmi omezený počet scénářů, pro které Azure AD Graph API může být vhodné; Další informace najdete v tématu Microsoft Graph nebo Azure AD Graph příspěvku na blogu v Office Dev Center.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Úspěšné požadavky na rozhraní Graph API je potřeba řešit na platný koncový bod a být správně naformátovaný, to znamená, musí obsahovat všechny požadované hlavičky a v případě potřeby datové části JSON v textu požadavku.A successful request to the Graph API must be addressed to a valid endpoint and be well-formatted, that is, it must contain any required headers and, if necessary, a JSON payload in the request body.Aplikace, který zadal žádost musí obsahovat přijatého z Azure AD, který prokáže, že má oprávnění pro přístup k prostředkům cílové žádosti o token.The app making the request must include a token received from Azure AD that proves that it is authorized to access the resources targeted by the request.Aplikace musí být schopna zpracovávat všechny odpovědí přijatých z rozhraní Graph API.The app must be able to handle any responses received from the Graph API.

Části v tomto tématu vám pomůže pochopit formát požadavky a odpovědi použít s rozhraní Graph API.The sections in this topic will help you understand the format of requests and responses used with the Graph API.

Ověřování a autorizace Authentication and authorization

Každý požadavek pro rozhraní Graph API musí mít nosiče tokenem vydaným službou Azure Active Directory připojen.Every request to the Graph API must have a bearer token issued by Azure Active Directory attached.Token má u sebe informace o aplikaci, přihlášeného uživatele (v případě přidělená oprávnění), ověřování a činnosti na adresář, který vaše aplikace je autorizovaný k provedení.The token carries information about your app, the signed-in user (in the case of delegated permissions), authentication, and the operations on the directory that your app is authorized to perform.Identifikátor tohoto tokenu je uložený v autorizace hlavičky žádosti.This token is carried in the Authorization header of the request.Například (token byl zkrácen. jako stručný výtah):For example (the token has been shortened for brevity):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

Rozhraní Graph API provede ověřování založené na obory oprávnění OAuth 2.0 v tokenu.The Graph API performs authorization based on OAuth 2.0 permission scopes present in the token.Další informace o oborech oprávnění, která vystavuje rozhraní Graph API najdete v tématu obory oprávnění rozhraní API grafu.For more information about the permission scopes that the Graph API exposes, see Graph API Permission Scopes.

Aby vaše aplikace k ověření s Azure AD a zavolat rozhraní Graph API musíte ho přidat do vašeho klienta a nakonfigurovat ji tak, aby vyžadovala oprávnění (obory oprávnění OAuth 2.0) pro Windows Azure Active Directory.In order for your app to authenticate with Azure AD and call the Graph API, you must add it to your tenant and configure it to require permissions (OAuth 2.0 permission scopes) for Windows Azure Active Directory.Informace o přidávání a konfiguraci aplikace naleznete v tématu integrace aplikací s Azure Active Directory.For information about adding and configuring an app, see Integrating Applications with Azure Active Directory.

Azure AD používá protokol ověřování OAuth 2.0.Azure AD uses the OAuth 2.0 authentication protocol.Můžete získat další informace o protokolu OAuth 2.0 ve službě Azure AD, včetně podporovaných toky a využít tokeny v OAuth 2.0 ve službě Azure AD.You can learn more about OAuth 2.0 in Azure AD, including supported flows and access tokens in OAuth 2.0 in Azure AD.

Koncový bod adresování Endpoint addressing

K provádění operací s rozhraní Graph API, můžete odesílat požadavky HTTP pomocí podporované metody – obvykle získat, POST, PATCH, PUT nebo odstranit--koncový bod, který je cílem služby, kolekci prostředků, jednotlivé zdroje, navigační vlastnost prostředku, nebo funkce nebo akce, které jsou vystavené službu.To perform operations with the Graph API, you send HTTP requests with a supported method - typically GET, POST, PATCH, PUT, or DELETE -- to an endpoint that targets the service, a resource collection, an individual resource, a navigation property of a resource, or a function or action exposed by the service.Koncové body jsou vyjádřené jako adresy URL.Endpoints are expressed as URLs.

Následující část popisuje základní formát koncový bod rozhraní Graph API:The following describes the basic format of a Graph API endpoint:

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

Následující součásti tvoří adresa URL:The following components comprise the URL:

Poznámka:: V některých případech při čtení kolekce prostředků, lze přidat parametry dotazu OData na žádost o k filtrování, řazení a stránka sadu výsledků dotazu.Note: In some cases, when reading resource collections, OData query parameters can be added to the request to filter, order, and page the result set.Další informace najdete v tématu parametry dotazu OData v tomto tématu.For more information, see the OData query parameters section in this topic.

Identifikátor klienta {tenant_id} Tenant identifier {tenant_id}

Můžete určit cílového klienta požadavku čtyři způsoby:You can specify the target tenant of a request in one of four ways:

  • ID objektu klientem.By tenant object ID.Identifikátor GUID, který byl přiřazen při vytvoření klienta.The GUID that was assigned when the tenant was created.To lze nalézt v objectId vlastnost TenantDetail objektu.This can be found in the objectId property of the TenantDetail object.Následující adresa URL ukazuje, jak vyřešit kolekce prostředků uživatele pomocí objektu klienta ID:The following URL shows how to address the users resource collection by using the tenant object ID:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Pomocí ověření (registrovaný) název domény.By verified (registered) domain name.Jeden z názvů domén, které jsou registrovány pro klienta.One of the domain names that are registered for the tenant.Ty lze najít v verifiedDomains vlastnost TenantDetail objektu.These can be found in the verifiedDomains property of the TenantDetail object.Následující adresa URL ukazuje, jak vyřešit kolekci prostředků uživatelů klienta, který má doménu contoso.com:The following URL shows how to address the users resource collection of a tenant that has the domain contoso.com:
    https://graph.windows.net/contoso.com/users?api-version=1.6.https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Pomocí myOrganization alias.By using the myOrganization alias.Tento alias je k dispozici pouze při použití udělení autorizačního kódu OAuth typu (s rameny-3) ověřování; To znamená, že při použití obor delegovaná oprávnění.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.Alias se nerozlišují malá a velká písmena.The alias is not case sensitive.Nahradí objekt domény ID nebo klienta v adrese URL.It replaces the object ID or tenant domain in the URL.Pokud alias se používá, rozhraní Graph API klienta odvozená z deklarací identity předkládaných v tokenu připojené k požadavku.When the alias is used, Graph API derives the tenant from the claims presented in the token attached to the request.Následující adresa URL ukazuje, jak vyřešit kolekci prostředků uživatelů klienta pomocí tento alias:The following URL shows how to address the users resource collection of a tenant using this alias:
    https://graph.windows.net/myorganization/users?api-version=1.6.https://graph.windows.net/myorganization/users?api-version=1.6.

  • Pomocí me alias.By using the me alias.Tento alias je k dispozici pouze při použití udělení autorizačního kódu OAuth typu (s rameny-3) ověřování; To znamená, že při použití obor delegovaná oprávnění.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.Alias se nerozlišují malá a velká písmena.The alias is not case sensitive.Nahradí objekt domény ID nebo klienta v adrese URL.It replaces the object ID or tenant domain in the URL.Pokud alias se používá, rozhraní Graph API odvozená z deklarací identity předkládaných v připojené k žádosti o token uživatele.When the alias is used, Graph API derives the user from the claims presented in the token attached to the request.Následující adresa URL Chcete-li vyřešit tento alias pomocí přihlášeného uživatele:The following URL to address the signed-in user using this alias:
    https://graph.windows.net/me?api-version=1.6.https://graph.windows.net/me?api-version=1.6.

Poznámka:: použijete me zástupce výhradně pro cíl operace u přihlášeného uživatele.Note: You use me alias solely to target operations against the signed-in user.Další informace najdete v tématu podepsaná in User Operations.For more information, see Signed-in User Operations.

Cesta prostředku {resource_path} Resource path {resource_path}

Zadáte {resource_path} odlišně v závislosti na tom, jestli jsou cílené na kolekci prostředků, jednotlivé zdroje, navigační vlastnost prostředku, funkci nebo akce vystavuje u klienta, nebo funkci nebo akce, které jsou zveřejněné na prostředek.You specify the {resource_path} differently depending on whether you are targeting a resource collection, an individual resource, a navigation property of a resource, a function or action exposed on the tenant, or a function or action exposed on a resource.

CílTargetCestaPathVysvětleníExplanation
Metadata službyService Metadata/$metadataVrátí metadata dokumentu služby.Returns the service metadata document.Následující příklad cíle služby metadata pro contoso.com tenanta:The following example targets service metadata using the contoso.com tenant:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Poznámka:: bez ověřování je potřeba načíst metadata služby.Note: No authentication is necessary to read the service metadata.
Kolekce prostředkůResource collection/{resource_collection}Cílem kolekci prostředků, jako jsou uživatelé nebo skupiny v klientovi.Targets a resource collection, such as users or groups in the tenant.Tuto cestu můžete použít ke čtení prostředků v kolekci a v závislosti na typu prostředek, k vytvoření nového prostředku v klientovi.You can use this path to read resources in the collection, and, depending on the resource type, to create a new resource in the tenant.V mnoha případech můžete další vylepšení sada výsledků vrácená čtení přidáním parametry dotazu k filtrování, řazení nebo stránky výsledky.In many cases the result set returned by a read can be further refined by the addition of query parameters to filter, order, or page the results.Následující příklad cílem kolekci uživatelů:The following example targets the user collection:
https://graph.windows.net/myorganization/users?api-version=1.6
Jediný zdrojSingle resource/{resource_collection}/{resource_id}Cílem konkrétní prostředek v klientovi, například uživatele, obraťte se na organizace nebo skupinu.Targets a specific resource in a tenant, such as a user, organizational contact, or group.Pro většinu prostředky resource_id je ID objektu.For most resources the resource_id is the object ID.Některé prostředky povolit další specifikátory; například uživatelé mohou být také určena hlavní název uživatele (UPN).Some resources allow additional specifiers; for example, users can be also specified by user principal name (UPN).V závislosti na prostředek můžete tuto cestu potřebujete deklarované vlastnosti prostředku, chcete-li upravit jeho deklarované vlastnosti nebo odstranit prostředek.Depending on the resource, you can use this path to get the declared properties of the resource, to modify its declared properties, or to delete the resource.Následující příklad zaměřena uživatele john@contoso.com:The following example targets the user john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Vlastnost navigace (objekty)Navigation property (objects)/{resource_collection}/{resource_id}/{property_name}Cílem vlastnost navigace konkrétní prostředek, jako je například správce uživatele nebo členství ve skupině nebo členové skupiny.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.Tuto cestu můžete vrátit objekt nebo objekty odkazuje navigační vlastnost target.You can use this path to return the object or objects referenced by the target navigation property.Následující příklad cílem správce john@contoso.com:The following example targets the manager of john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Poznámka:: Tato forma adresování je k dispozici pouze pro čtení.Note: This form of addressing is only available for reads.
Vlastnost navigace (odkazy)Navigation property (links)/{resource_collection}/{resource_id}/$links/{property_name}Cílem vlastnost navigace konkrétní prostředek, jako je například správce uživatele nebo členství ve skupině nebo členové skupiny.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.Tato forma adresování můžete číst a upravovat navigační vlastnost.You can use this form of addressing to both read and modify a navigation property.Na čtení odkazovaný vlastností objektů jako jeden nebo více odkazů v textu odpovědi.On reads, the objects referenced by the property are returned as one or more links in the response body.Na zápis jsou objekty zadané jako jeden nebo více odkazů v textu požadavku.On writes, the objects are specified as one or more links in the request body.Následující příklad cílem vlastnost manager john@contoso.com:The following example targets the manager property of john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Funkce nebo akce, které jsou zveřejněné na klientaFunctions or actions exposed on the tenant/{function_name}Zaměřuje na funkce nebo akce, které jsou umístěné na klienta.Targets a function or action exposed at the tenant.Funkce a akce jsou obvykle spuštěny se požadavek POST a můžou obsahovat text žádosti.Functions and actions are typically invoked with a POST Request and may include a request body.Následující příklad cíle isMemberOf funkce:The following example targets the isMemberOf function:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funkce nebo akce, které jsou zveřejněné na prostředek.Functions or actions exposed on a resource./{resource_collection}/{resource_id}/{function_name}Zaměřuje na funkce nebo akce, které jsou zveřejněné na prostředek.Targets a function or action exposed on a resource.Funkce a akce jsou obvykle spuštěny se požadavek POST a můžou obsahovat text žádosti.Functions and actions are typically invoked with a POST Request and may include a request body.Následující příklad cíle getMemberGroups funkce:The following example targets the getMemberGroups function:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Verze rozhraní Graph API {api-version} Graph API version {api-version}

Můžete použít api-version parametr k cílení na konkrétní verzi rozhraní Graph API pro operaci dotazu.You use the api-version query parameter to target a specific version of the Graph API for an operation.Tento parametr je povinný.This parameter is required.

Hodnota api-version parametr může být jedna z následujících akcí:The value for the api-version parameter can be one of the following:

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

Například následující adresu URL cílem kolekci uživatelů pomocí rozhraní Graph API verzi 1.6:For example the following URL targets the user collection using Graph API version 1.6:

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

Další informace o verzích a funkce změny mezi verzemi najdete v tématu Správa verzí.For more information about versions and feature changes between versions, see Versioning.

Parametry dotazu OData OData query parameters

V mnoha případech při čtení kolekce prostředků, můžete filtrování, řazení a stránka připojením parametry dotazu OData k žádosti o sadu výsledků dotazu.In many cases when you read a collection of resources, you can filter, sort, and page the result set by attaching OData query parameters to your request.

Rozhraní Graph API podporuje následující parametry dotazu Odata:The Graph API supports the following Odata query parameters:

  • $filter$filter
  • $batch$batch
  • $expand$expand
  • $orderby$orderby
  • $top$top
  • $skiptoken a předchozí stránka$skiptoken and previous-page

V tématu podporované dotazy, filtrů a stránkování možnosti Další informace o podporovaných OData dotaz parametrů a jejich omezení v rozhraní Graph API.See Supported Queries, Filters, and Paging Options for more information about supported OData query parameters and their limitations in the Graph API.

Hlavičkách žádostí a odpovědí Request and response headers

V následující tabulce jsou společné hlavičky HTTP, které jsou používány požadavků s rozhraní Graph API.The following table shows common HTTP headers used in requests with the Graph API.Smyslem není jako komplexní.It is not meant to be comprehensive.

Hlavička požadavkuRequest HeaderPopisDescription
AutorizaceAuthorizationVyžaduje se.Required.Nosiče tokenem vydaným službou Azure Active Directory.A bearer token issued by Azure Active Directory.V tématu ověřování a autorizace v tomto tématu pro další informace.See Authentication and Authorization in this topic for more information.
Content-TypeContent-TypeVyžaduje, pokud je přítomen textu požadavku.Required if request body is present.Typ média obsahu v textu požadavku.The media type of the content in the request body.Použijte application/json.Use application/json.Parametry může být součástí typ média.Parameters may be included with the media type.
Poznámka:: application/atom + xml a aplikace/xml (odkazy) jsou podporována, ale nedoporučuje se, jak z důvodů výkonu a protože podpora přestanou XML v budoucí verzi.Note: application/atom+xml and application/xml (for links) are supported but are not recommended both for performance reasons and because support for XML will be deprecated in a future release.
Content-LengthContent-LengthVyžaduje, pokud je přítomen textu požadavku.Required if request body is present.Délka požadavku v bajtech.The length of the request in bytes.

V následující tabulce jsou společné hlavičky HTTP v odpovědi vrácené rozhraní Graph API.The following table shows common HTTP headers returned in responses by the Graph API.Smyslem není jako komplexní.It is not meant to be comprehensive.

Hlavička odpovědiResponse HeaderPopisDescription
Content-TypeContent-TypeTyp média obsahu v textu odpovědi.The media type of the content in the response body.Výchozí hodnota je application/json.The default is application/json.Požadavky pro uživatele miniaturu fotografie vracet bitovou kopii nebo jpeg ve výchozím nastavení.Requests for user thumbnail photos return image/jpeg by default.
UmístěníLocationVrácený v odpovědi na požadavky POST, které v adresáři vytvořte nový prostředek (objekt).Returned in responses to POST requests that create a new resource (object) in the directory.Obsahuje identifikátor URI nově vytvořený prostředek.Contains the URI of the newly created resource.
ocp-aad-diagnostics-server-nameocp-aad-diagnostics-server-nameIdentifikátor pro server, který provést požadovanou operaci.The identifier for the server that performed the requested operation.
OCP-aad relace keyocp-aad-session-keyKlíč, který identifikuje aktuální relaci s adresářovou službou.The key that identifies the current session with the directory service.

Minimálně doporučujeme že provést pro každý požadavek následující:At a minimum, we recommend you do the following for each request:

  1. Přihlaste se odeslání žádosti o přesného časového razítka.Log an accurate time stamp of the request submission.
  2. Odesílání a přihlaste se client-request-id.Send and log the client-request-id.
  3. Přihlaste se kód odpovědi HTTP a request-id.Log the HTTP response code and request-id.

Poskytování informací v těchto protokolech pomůže řešení problémů při žádosti o nápovědy a podpory společnosti Microsoft.Providing information in such logs will help Microsoft troubleshoot issues when you ask for help or support.

Těla požadavku a odpovědiRequest and response bodies

V datové části JSON nebo XML nelze odesílat textem žádosti pro požadavky POST, PATCH a PUT.Request bodies for POST, PATCH, and PUT requests can be sent in JSON or XML payloads.V datové části JSON nebo XML se může vracet odpovědi serveru.Server responses can be returned in JSON or XML payloads.Datové části v textem žádosti můžete zadat pomocí Content-Type hlavička požadavku a odpovědi s použitím Accept hlavička požadavku.You can specify the payload in request bodies by using the Content-Type request header and in responses by using the Accept request header.

Důrazně doporučujeme použít datové části JSON v požadavky a odpovědi s rozhraní Graph API. Toto je i z důvodů výkonu a protože přestanou XML v budoucí verzi.We strongly recommend that you use JSON payloads in requests and responses with the Graph API. This is both for performance reasons and because XML will be deprecated in a future release.

Pokročilé funkceAdvanced features

V předchozích částech je popsané, formátování základní požadavky a odpovědi s rozhraní Graph API.The preceding sections discussed the formatting of basic requests and responses with the Graph API.Nabízí vyspělejší funkce, může přidat parametrů řetězce dotazu další nebo mít výrazně odlišné požadavku a odpovědi těla než základní operace, jak jsme vysvětlili výše v tomto tématu.More advanced features may add additional query string parameters or have significantly different request and response bodies than the basic operations discussed previously in this topic.

Tyto funkce patří:These features include:

  • Dávkové zpracování: rozhraní Graph API podporuje dávkové zpracování.Batch Processing: The Graph API supports batching.Odesílání žádostí v dávkách snižuje zpátečních cest k serveru, což snižuje nároky na síť a pomáhá vaší operace dokončeny rychleji.Sending requests in batches reduces round trips to the server, which reduces network overhead and helps your operations complete more quickly.Další informace o dávkové zpracování pomocí rozhraní Graph API najdete v tématu dávkové zpracování.For more information about batch processing with the Graph API, see Batch Processing.
  • Rozdílovou dotazu: rozhraní Graph API podporuje provádění rozdílové dotazy.Differential Query: The Graph API supports performing differential queries.Rozdílovou dotazu umožňuje vrátit změny na konkrétní entity v klientovi mezi požadavky vydané v různých časech.Differential query allows you to return changes to specific entities in a tenant between requests issued at different times.Tato funkce se často používá k synchronizaci místní úložiště s změny u klienta.This feature is often used to sync a local store with changes on the tenant.Další informace o rozdílové dotaz s rozhraní Graph API najdete v tématu rozdílové dotazu.For more information about differential query with the Graph API, see Differential Query.

Další zdroje informací Additional resources

© 2018 Microsoft