Megosztás a következőn keresztül:

Műveletek áttekintése |} Graph API fogalmak

  • Cikk

Az Azure Active Directory (AD) Graph API egy olyan OData 3.0 kompatibilis szolgáltatás, amely olvasási és módosítási objektumok, például a felhasználók, csoportok és a bérlő partnerek segítségével. Az Azure AD Graph API REST-végpontok elküldött HTTP-kéréseket a szolgáltatás használatával műveleteket szeretne végrehajtani mutatja. A következő szakaszok formátum kéréseket, és mi történik a válaszok, ha a Graph API segítségével olvasási és írási címtárerőforrásokkal, directory-funkciókat, illetve művelet hívása, vagy hajtsa végre a lekérdezéseket a címtár kapcsolatos általános adatok megadása. Részletesebb információ a konkrét műveletek címtárerőforrásokkal végrehajtása, témakörében a megfelelő műveleteket a Azure AD Graph API-referencia.

Fontos

Határozottan javasoljuk, hogy használjon Microsoft Graph helyett az Azure AD Graph API Azure Active Directory-erőforrások eléréséhez. A fejlesztéshez most összpontosítani Microsoft Graph, és nincs további fejlesztések Azure AD Graph API tervbe van véve. Nagyon korlátozott számú forgatókönyvek, amelyek az Azure AD Graph API továbbra is megfelelő lehet; További információkért lásd: a Microsoft Graph vagy az Azure AD Graph blogbejegyzés az Office-fejlesztői központban.

A Graph API a kérelem sikeres kell küldeni egy érvényes végpontot, és jól formázott kell, ez azt jelenti, hogy minden szükséges fejlécek kell tartalmaznia, és ha szükséges, egy JSON-adattartalmat a kérés törzsében. Az alkalmazás a kérést tartalmaznia kell egy Azure ad-, amely bizonyítja, hogy az a kérelem által célzott erőforrásokhoz való hozzáféréskor engedélyezett kapott jogkivonat. Az alkalmazás tudja kezelni a Graph API érkező válaszokat kell lennie.

A jelen témakör részei segítséget kérések és válaszok Graph API-val használt formátuma ismertetése.

Hitelesítés és engedélyezés

A Graph API minden kérelemnél rendelkeznie kell egy tulajdonosi jogkivonatot csatolt Azure Active Directory által kibocsátott. A token végzi információkat az alkalmazás, (delegált jogosultságokkal) esetén a bejelentkezett felhasználó, hitelesítés és a műveletek, amely az alkalmazás végrehajtására jogosult. Ez a token végzik a engedélyezési a kérelem fejlécében. (A token lerövidítette kivonatosan mutatja) például:

Authorization: Bearer eyJ0eX ... FWSXfwtQ

A Graph API a jogkivonat jelenlegi OAuth 2.0-engedélyhatókörök alapján engedélyezési hajt végre. A engedélyhatókörök, amely mutatja a Graph API-val kapcsolatos további információkért lásd: Graph API-Engedélyhatókörök.

Ahhoz, hogy az az Azure AD hitelesíti, és hívja meg a Graph API-alkalmazás vegye fel a bérlői és konfigurálja úgy, hogy (OAuth 2.0-engedélyhatókörök) engedély szükséges a Windows Azure Active Directoryban. Hozzáadásával és az alkalmazás konfigurálásával kapcsolatos további információkért lásd: alkalmazások integrálása az Azure Active Directoryval.

Az Azure AD az OAuth 2.0 hitelesítési protokollt használja. Az Azure AD, beleértve a támogatott adatfolyamok OAuth 2.0 kapcsolatos további és a hozzáférési tokenek OAuth 2.0, az Azure AD.

Végpont-címzés

Graph API-val műveletek végrehajtásához HTTP-kérelmek küldése a támogatott módszere – általában, közzétett, javítás, PUT, vagy törlés – egy végpontot, amelynek célpontja a szolgáltatást, erőforrás-gyűjteményt, egyedi erőforrás, navigálási tulajdonság egy erőforrás vagy egy funkció vagy művelet a szolgáltatás által elérhetővé tett. Végpont URL-jeiként szerint van megadva.

A következő egy grafikonon API-végpont alapszintű formátumát mutatja be:

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

A következő összetevőket foglalja magában az URL-cím:

Megjegyzés:: bizonyos esetekben, amikor erőforrás gyűjtemények olvasása, a lekérdezés-paraméterek OData lehet hozzáadni a a kérelmek szűrése, rendezése és az eredménykészlet lapon. További információkért lásd: a lekérdezési paraméterek OData szakaszában talál.

Bérlői azonosító {tenant_id}

A cél bérlő kérelem négy módon adhatja meg:

  • A bérlő objektumazonosító. A GUID, amikor a bérlő létre lett hozva hozzá volt rendelve. Ez megtalálhatók a objectId tulajdonsága a TenantDetail objektum. A következő URL-címet a bérlő objektum azonosítója használatával a felhasználók erőforrás-gyűjteményt cím mutatja be:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Az ellenőrzött (regisztrált) tartománynév. A bérlő regisztrált a tartomány neveinek egyike. Ezek itt található: a verifiedDomains tulajdonsága a TenantDetail objektum. A következő URL-cím bemutatja, hogyan kezelje a felhasználók erőforrás-gyűjteményt, amely a contoso.com tartomány rendelkezik egy bérlő:
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Használatával a myOrganization alias. Ez az alias csak akkor használható, ha hitelesítéssel OAuth Hitelesítésengedélyezési kód típusa (3-Egyszárú); Ez azt jelenti, hogy engedélyt hatókör használatakor. Az alias nincs kis-és nagybetűket. Lecseréli a objektum azonosítója vagy bérlői tartomány URL-címét. Az alias használata esetén Graph API a bérlő származik a jogkivonat a kérelemhez jelenik meg a jogcímeket. A következő URL-cím bemutatja, hogyan kezelje a felhasználók erőforrás-gyűjteményt a bérlő jelenlegi alias használatával:
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • Használatával a me alias. Ez az alias csak akkor használható, ha hitelesítéssel OAuth Hitelesítésengedélyezési kód típusa (3-Egyszárú); Ez azt jelenti, hogy engedélyt hatókör használatakor. Az alias nincs kis-és nagybetűket. Lecseréli a objektum azonosítója vagy bérlői tartomány URL-címét. Az alias használata esetén Graph API a felhasználó származik a jogkivonat a kérelemhez jelenik meg a jogcímeket. Az alábbi URL-cím a felhasználói bejelentkezés jelenlegi alias használatával:
    https://graph.windows.net/me?api-version=1.6.

Megjegyzés:: használata me alias kizárólag a bejelentkezett felhasználó cél műveleteket. További információkért lásd: aláírt felhasználói műveletek.

Erőforrás elérési útja {resource_path}

Adja meg, hogy a {resource_path} másképp attól függően, hogy céloz meg egy erőforrás-gyűjteményt, egyedi erőforrás, erőforrás navigálási tulajdonságot, egy funkció vagy művelet kitett a tenant, vagy egy erőforrás elérhetővé tett egy függvényt vagy a művelet.

Cél Elérési út Magyarázat
Service Metadata /$metadata A metaadat-dokumentum adja vissza. A következő példa célok szolgáltatás metaadatai contoso.com a bérlőnek a használatával:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Megjegyzés:: hitelesítés nem szükséges szolgáltatás metaadatainak olvasásához.
Erőforrás-gyűjteményt /{resource_collection} Erőforrás-gyűjteményt, például a felhasználók vagy csoportok a bérlő célozza. Az elérési út használatával olvassa el a gyűjteményben, és attól függően, hogy az erőforrás típusa, adhat hozzá egy új erőforrást a bérlői erőforrásokhoz. Sok esetben egy olvasási által visszaadott eredménykészlet is lehet további kifinomultabb lett való, sorrendben, vagy az eredmények lapon lekérdezési paraméterek hozzáadásával. Az alábbi példában a felhasználói gyűjtemény célja:
https://graph.windows.net/myorganization/users?api-version=1.6
Egyetlen erőforrás /{resource_collection}/{resource_id} Egy adott erőforrás bérlőjében, például felhasználó, szervezeti forduljon vagy csoportot célozza. A legtöbb erőforrást a resource_id az az objektum azonosítója. Bizonyos erőforrások engedélyezése további kulcsszavak; például felhasználók is megadható egyszerű felhasználónév (UPN). Attól függően, hogy az erőforrás hozhat ezt az elérési utat az erőforrás, annak deklarált tulajdonságait, vagy az erőforrás törlése deklarált tulajdonságait olvassa be. Az alábbi példában a felhasználói megcélzó john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Navigálási tulajdonság (objektumok) /{resource_collection}/{resource_id}/{property_name} Egy adott erőforrás, például a felhasználó kezelője vagy csoporttagságok vagy egy csoport tagjai navigálási tulajdonság célozza. Az elérési út segítségével az objektum vagy a cél navigálási tulajdonság által hivatkozott objektumokat adja vissza. Az alábbi példa célozza felettesét john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Megjegyzés:: ezt az űrlapot az címzési csak érhető el az olvasási műveletek.
Navigálási tulajdonság (hivatkozások) /{resource_collection}/{resource_id}/$links/{property_name} Egy adott erőforrás, például a felhasználó kezelője vagy csoporttagságok vagy egy csoport tagjai navigálási tulajdonság célozza. Az űrlap címzés segítségével olvasására és egy navigációs tulajdonság módosítására. Az olvasási a tulajdonság által hivatkozott objektumok vissza, az adott válasz törzsének egy vagy több hivatkozások. Az írási műveletekről az objektumok a kérelem törzsében szereplő egy vagy több hivatkozások formájában vannak megadva. Az alábbi példa célozza az manager tulajdonsága john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Funkciók, illetve a tenant kitett művelet /{function_name} Egy függvény vagy a bérlő kitett művelet célozza. Függvények és a műveletek általában által elindított egy POST kérést, és előfordulhat, hogy tartalmazza a kérés törzsében. A következő példa célokat a isMemberOf függvény:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funkciók, illetve kikerültek erőforrás a művelet. /{resource_collection}/{resource_id}/{function_name} Egy függvény vagy kitett erőforrásra vonatkozó művelet célozza. Függvények és a műveletek általában által elindított egy POST kérést, és előfordulhat, hogy tartalmazza a kérés törzsében. A következő példa célokat a getMemberGroups függvény:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

{Az api-version} Graph API-verzió

Használja a api-version lekérdezésparaméter, amelyekre a Graph API művelet egy adott verziójához. Ez a paraméter megadása kötelező.

Az érték a api-version paraméter a következők egyike lehet:

  • "béta"
  • "1.6"
  • "1.5"
  • "2013/11/08"
  • "2013/04/05"

A következő URL-címe például a Graph API-jával 1.6-os verziójának felhasználógyűjteményt célozza:

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

Verziók és a szolgáltatás módosítások verziói között kapcsolatos további információkért lásd: Versioning.

Lekérdezés-paraméterek OData

Sok esetben olvassa el az erőforrásokat, amikor is szűrése, rendezése, és az eredményhalmazban, hogy a kérelem lekérdezési paraméterek OData csatolása lapon.

A Graph API a következő Odata-lekérdezési paramétereket támogatja:

  • $filter
  • $batch
  • Bontsa ki a $
  • $orderby
  • $top
  • $skiptoken és az előző lapra

Lásd: támogatott lekérdezések, szűrők és beállítások lapozás további információ a támogatott OData lekérdezési paramétereit és azok korlátai, a Graph API-ban.

Kérés- és válaszfejlécekről

A következő táblázat a gyakori HTTP-fejléceket, a Graph API-val rendelkező kérelmek esetében használt. Nem célja, hogy átfogó.

Fejléc Description
Engedélyezés Szükséges. Egy Azure Active Directory által kibocsátott tulajdonosi jogkivonatot. Lásd: hitelesítési és engedélyezési című témakörben talál további információt.
Content-Type Szükséges, ha a kérelem törzsében megtalálható-e. A tartalom a kérelem törzsében szereplő adathordozó-típusát. Az application/json használja. Paraméterek az adathordozó-típus része lehet.
Megjegyzés:: application/atom + xml és application/XML-kódja (hivatkozások) is támogatja, de nem ajánlott mind a teljesítményre vonatkozó megfontolásból, és mivel támogatása XML egy későbbi kiadásban elavulttá válik.
Content-Length Szükséges, ha a kérelem törzsében megtalálható-e. A kérelem bájtban hosszát.

Az alábbi táblázat a gyakori HTTP-fejléceket, a Graph API adott vissza. Nem célja, hogy átfogó.

Válaszfejléc Description
Content-Type A tartalom az adott válasz törzsének adathordozó-típusát. Az alapértelmezett érték az application/json. A felhasználó miniatűr fényképek kérelem kép/jpeg alapértelmezés szerint adja vissza.
Tartózkodási hely A visszaadott megválaszolhatók a POST kérelmek, hozzon létre egy új erőforrást (objektum) a címtárban. Az újonnan létrehozott erőforrás URI tartalmazza.
ocp-aad-diagnostics-server-name A kiszolgáló által végrehajtott a kért művelet azonosítója.
az OCP-aad-munkamenet-kulcs A kulcs, amely azonosítja az aktuális munkamenet a directory szolgáltatással.

Legalább a ajánlott minden kérelem esetén a következőket teheti:

  1. A kérés küldése egy pontos időbélyegzőjét naplózása.
  2. Küldése és naplózása a client-request-id.
  3. A HTTP válaszkódot naplózása és request-id.

Ilyen a naplókban lévő információk biztosítása a segítségével a Microsoft problémák elhárításához, amikor a Súgó és támogatás kérjen.

Kérelem és válasz

A FELADÁS egy vagy több, a javítás és a PUT kérelmek kérelem szervek küldhetők JSON vagy XML hasznos adat található. Kiszolgáló válaszainak adhatók vissza a JSON- vagy XML hasznos adat található. Adhat meg a tartalom kérelem szervek használatával a Content-Type fejléc és a válaszok segítségével a Accept kérelem fejléce.

Határozottan javasoljuk, hogy a Graph API-t használjon JSON hasznos adatot kérelmeit és válaszait. Ez akkor is, a teljesítményre vonatkozó megfontolásból, és mivel XML egy későbbi kiadásban elavulttá válik.

A speciális funkciók

Az előző tárgyalja alapvető kérelmeit és válaszait a Graph API-val formázását. Fejlettebb szolgáltatásokat is előfordulhat, hogy adjon további lekérdezési karakterlánc paramétert, vagy jelentősen eltérő kérés és válasz szervezetek, mint a korábban a jelen témakörben bemutatott alapvető műveleteket.

Ezek a funkciók a következők:

  • A Batch-feldolgozási: A Graph API támogatja a kötegelés. Kérelmek küldése a kötegek csökkenti a kiszolgálókkal való adatváltások számát a kiszolgálóhoz, amely csökkenti a hálózati munkaterhet és segítséget nyújt a művelet gyorsabban fejeződik be. Kötegfeldolgozási Graph API-val kapcsolatos további információkért lásd: köteg feldolgozása.
  • Különbözeti lekérdezés: A Graph API támogatja a különbözeti lekérdezések végrehajtásához. Különbözeti lekérdezés lehetővé teszi, hogy módosításokat visszatérhet az adott bejegyzései szerepelnek a bérlők között különböző időpontokban kérelmet. Ez a szolgáltatás gyakran használják a tenant módosításait a helyi tárolójába szinkronizálására. Különbözeti lekérdezés Graph API-val kapcsolatos további információkért lásd: különbözeti lekérdezés.

További források