Operace přehled | Rozhraní Graph API koncepty
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. Azure AD Graph API zpřístupní koncové body REST, které odešlete žádostí HTTP, abyste mohli provádět operace pomocí služby. 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ář. 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.
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. Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro 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.
Ú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. 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. Aplikace musí být schopna zpracovávat všechny odpovědí přijatých z rozhraní 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.
Ověřování a autorizace
Každý požadavek pro rozhraní Graph API musí mít nosiče tokenem vydaným službou Azure Active Directory připojen. 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í. Identifikátor tohoto tokenu je uložený v autorizace hlavičky žádosti. Například (token byl zkrácen. jako stručný výtah):
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Rozhraní Graph API provede ověřování založené na obory oprávnění OAuth 2.0 v tokenu. Další informace o oborech oprávnění, která vystavuje rozhraní Graph API najdete v tématu obory oprávnění rozhraní API grafu.
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. Informace o přidávání a konfiguraci aplikace naleznete v tématu integrace aplikací s Azure Active Directory.
Azure AD používá protokol ověřování OAuth 2.0. 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.
Koncový bod adresování
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. Koncové body jsou vyjádřené jako adresy URL.
Následující část popisuje základní formát koncový bod rozhraní Graph API:
https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}
Následující součásti tvoří adresa URL:
- Služba kořenové: je kořenový adresář pro všechny požadavky rozhraní Graph API
https://graph.windows.net. - Klienta identifikátor {tenant_id}: identifikátor pro klienta, cíle žádosti.
- Cesta prostředku {resource_path}: cesta k prostředku – například uživatele nebo skupinu – který cíle žádosti.
- Graf verze rozhraní API {api_version}: verzi rozhraní Graph API cílem žádosti. To je vyjádřena jako parametr dotazu a vyžaduje se.
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. Další informace najdete v tématu parametry dotazu OData v tomto tématu.
Identifikátor klienta {tenant_id}
Můžete určit cílového klienta požadavku čtyři způsoby:
ID objektu klientem. Identifikátor GUID, který byl přiřazen při vytvoření klienta. To lze nalézt v objectId vlastnost TenantDetail objektu. Následující adresa URL ukazuje, jak vyřešit kolekce prostředků uživatele pomocí objektu klienta ID:
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.Pomocí ověření (registrovaný) název domény. Jeden z názvů domén, které jsou registrovány pro klienta. Ty lze najít v verifiedDomains vlastnost TenantDetail objektu. Následující adresa URL ukazuje, jak vyřešit kolekci prostředků uživatelů klienta, který má doménu contoso.com:
https://graph.windows.net/contoso.com/users?api-version=1.6.Pomocí
myOrganizationalias. 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í. Alias se nerozlišují malá a velká písmena. Nahradí objekt domény ID nebo klienta v adrese 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. Následující adresa URL ukazuje, jak vyřešit kolekci prostředků uživatelů klienta pomocí tento alias:
https://graph.windows.net/myorganization/users?api-version=1.6.Pomocí
mealias. 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í. Alias se nerozlišují malá a velká písmena. Nahradí objekt domény ID nebo klienta v adrese 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. Následující adresa URL Chcete-li vyřešit tento alias pomocí přihlášeného uživatele: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. Další informace najdete v tématu podepsaná in User Operations.
Cesta prostředku {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.
| Cíl | Cesta | Vysvětlení |
|---|---|---|
| Metadata služby | /$metadata |
Vrátí metadata dokumentu služby. Následující příklad cíle služby metadata pro contoso.com tenanta: 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. |
| Kolekce prostředků | /{resource_collection} |
Cílem kolekci prostředků, jako jsou uživatelé nebo skupiny v klientovi. 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. 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. Následující příklad cílem kolekci uživatelů: https://graph.windows.net/myorganization/users?api-version=1.6 |
| Jediný zdroj | /{resource_collection}/{resource_id} |
Cílem konkrétní prostředek v klientovi, například uživatele, obraťte se na organizace nebo skupinu. Pro většinu prostředky resource_id je ID objektu. Některé prostředky povolit další specifikátory; například uživatelé mohou být také určena hlavní název uživatele (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. Následující příklad zaměřena uživatele john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6 |
| Vlastnost navigace (objekty) | /{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. Tuto cestu můžete vrátit objekt nebo objekty odkazuje navigační vlastnost target. Následující příklad cílem správce 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í. |
| Vlastnost navigace (odkazy) | /{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. Tato forma adresování můžete číst a upravovat navigační vlastnost. Na čtení odkazovaný vlastností objektů jako jeden nebo více odkazů v textu odpovědi. Na zápis jsou objekty zadané jako jeden nebo více odkazů v textu požadavku. Následující příklad cílem vlastnost manager 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 klienta | /{function_name} |
Zaměřuje na funkce nebo akce, které jsou umístěné na klienta. Funkce a akce jsou obvykle spuštěny se požadavek POST a můžou obsahovat text žádosti. Následující příklad cíle isMemberOf funkce: https://graph.windows.net/myorganization/isMemberOf?api-version=1.6. |
| Funkce nebo akce, které jsou zveřejněné na prostředek. | /{resource_collection}/{resource_id}/{function_name} |
Zaměřuje na funkce nebo akce, které jsou zveřejněné na prostředek. Funkce a akce jsou obvykle spuštěny se požadavek POST a můžou obsahovat text žádosti. Následující příklad cíle getMemberGroups funkce: https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6. |
Verze rozhraní Graph API {api-version}
Můžete použít api-version parametr k cílení na konkrétní verzi rozhraní Graph API pro operaci dotazu. Tento parametr je povinný.
Hodnota api-version parametr může být jedna z následujících akcí:
- "beta"
- "1.6"
- "1.5"
- "2013/11/08"
- "2013/04/05"
Například následující adresu URL cílem kolekci uživatelů pomocí rozhraní Graph API verzi 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í.
Parametry dotazu OData
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.
Rozhraní Graph API podporuje následující parametry dotazu Odata:
- $filter
- $batch
- $expand
- $orderby
- $top
- $skiptoken a předchozí stránka
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.
Hlavičkách žádostí a odpovědí
V následující tabulce jsou společné hlavičky HTTP, které jsou používány požadavků s rozhraní Graph API. Smyslem není jako komplexní.
| Hlavička požadavku | Popis |
|---|---|
| Autorizace | Vyžaduje se. Nosiče tokenem vydaným službou Azure Active Directory. V tématu ověřování a autorizace v tomto tématu pro další informace. |
| Content-Type | Vyžaduje, pokud je přítomen textu požadavku. Typ média obsahu v textu požadavku. Použijte application/json. Parametry může být součástí typ média. 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. |
| Content-Length | Vyžaduje, pokud je přítomen textu požadavku. Délka požadavku v bajtech. |
V následující tabulce jsou společné hlavičky HTTP v odpovědi vrácené rozhraní Graph API. Smyslem není jako komplexní.
| Hlavička odpovědi | Popis |
|---|---|
| Content-Type | Typ média obsahu v textu odpovědi. Výchozí hodnota je application/json. Požadavky pro uživatele miniaturu fotografie vracet bitovou kopii nebo jpeg ve výchozím nastavení. |
| Umístění | Vrácený v odpovědi na požadavky POST, které v adresáři vytvořte nový prostředek (objekt). Obsahuje identifikátor URI nově vytvořený prostředek. |
| ocp-aad-diagnostics-server-name | Identifikátor pro server, který provést požadovanou operaci. |
| OCP-aad relace key | Klíč, který identifikuje aktuální relaci s adresářovou službou. |
Minimálně doporučujeme že provést pro každý požadavek následující:
- Přihlaste se odeslání žádosti o přesného časového razítka.
- Odesílání a přihlaste se
client-request-id. - Přihlaste se kód odpovědi HTTP a
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.
Těla požadavku a odpovědi
V datové části JSON nebo XML nelze odesílat textem žádosti pro požadavky POST, PATCH a PUT. V datové části JSON nebo XML se může vracet odpovědi serveru. 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.
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.
Pokročilé funkce
V předchozích částech je popsané, formátování základní požadavky a odpovědi s rozhraní 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.
Tyto funkce patří:
- Dávkové zpracování: rozhraní Graph API podporuje dávkové zpracování. 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. Další informace o dávkové zpracování pomocí rozhraní Graph API najdete v tématu dávkové zpracování.
- Rozdílovou dotazu: rozhraní Graph API podporuje provádění rozdílové dotazy. Rozdílovou dotazu umožňuje vrátit změny na konkrétní entity v klientovi mezi požadavky vydané v různých časech. Tato funkce se často používá k synchronizaci místní úložiště s změny u klienta. Další informace o rozdílové dotaz s rozhraní Graph API najdete v tématu rozdílové dotazu.