Microsoft Graph чыра спадчынныя REST-канцэнтры: каратаўнік рашэнняў да 2026 года

Запитаўніца ў чым-то некалькі некоректная

Кожны, хто під’ўязуе дапыт до дадзэнняў Microsoft 365, Entra ID, Teams чы Outlook, раней чы пазней шукае адказ на пытанне «REST API чы Microsoft Graph?». Це здаецца справядлівым выборам між двума варыянтамі, але на самай працы так не ёсць. Сам Microsoft Graph ёсць REST API. Калі люди говоряць пра гэта, яны насправе маюць на увазе наступнае:

Чы трэба продаваляйці вяртацца да старых, спецыяльных для кожнага сервісу REST-канцэнтраў (Azure AD Graph, Outlook REST API, SharePoint REST, EWS і іншыя), чы перейсці на аб’еднаны Microsoft Graph API?

У 2026 году даўнае запытанне паўтарыцца з рэальнымі канцэсіямі. Компанія Microsoft пасвятила апошнія тры годы закрыццю фрагментаваных API і перакананню всіх перейсці на Graph, прычаму канцэсія дзеяння калькі з іх вядзецца ўсьмо толькі за калькі тыдзёў. Чырвоным вы пабачыце апранаваныя назвы, інформацыю пра статус таго, што яшчэ працюе, порэванае прадставленне, а таксама процес прыняцтва рашэння, які можна застосаваць як да новых версій, так і да старых інтеграцый.

Апранаванне назв

REST — это архітэктурны стыль. Це не продукт, які трэба інсталаваць. API, які выкарыстоўвае дзеянні HTTP, такія як GET, POST, PATCH і DELETE, адносіцца да элементаў як да рэсурсаў па URL і зазвычай адмаўляецца JSON, можа справядліва называцца RESTful. Па гэтым ваказанню Microsoft Graph, Azure AD Graph, закрыты Outlook REST API і SharePoint REST таксама падпадаюць пад гэтыя крэтырі.

Microsoft Graph — это адынственны REST API, які абарачвае як Microsoft 365, так і Entra ID. Не трэба пераходзіць з аднаго канцэнтрау для пашты, іншага — для файлаў, і трэцьяго — для данных дырэктарыю. Усё знаходзіцца пад https://graph.microsoft.com/: корыстнікі, групы, пашта, календары, чаты Teams, файлы, апавяшэнні пра безпеку, а таксама, як недавна, і агенты AI.

Таму корыстным ўпорам являецца адынственны Graph у працоўнасупрацоўцы з старымі, спецыфічнымі для кожнага сервіса REST-інтерфейсамі. Тое, як зараз стояць тыя старыя API, мае вялікое значэнне, таму што ситуацыя быстра змінілася за апошні год.

Што ўсё ўжо працюе ў 2026 году

Якщо які-небудзь з вашых ресурсаў яшчэ праўяцца на graph.windows.net, вы вже запаздзілі; пачынаючы з середзіны ліпня 2026 года, гэты варыянт будзе недоступны прыблізна за калькі недзеў. Стары API Outlook REST вже не існуе больш чым два гады. Доступ трэціх сторон да EWS через Exchange Online будзе перакрыты ў гэты ўжо осень. Практычна кожны аргумент, які раней служыў падставай для застосоўвання аблікованага REST-канцэнтра, або вже не актуальны, або скора стане такім.

Microsoft вялікія часы зміняла гэтыя тэрміны, таму перад тым, як планаваць міграцыю, неабходна пацікавіцца актуальным канцэнтрам на сайце Microsoft Learn. Аднак напрамак развіцці працоўвае незменным вялікія гады: усе функцыі будуць адносаваны да Graph.

Graph проты старых канцэнтраў

У повсякдзеннай работе найважлівейшыя тры разлікі.

Аутентыкацыя

За адзін дзесятак гадоў гэты спадчынны функцыонал сабраў вялікі набор варыянтаў аутэнтыкацыі: Basic Auth, NTLM, Kerberos, а таксама Azure Access Control Service, ад каго залежалі дадаткі SharePoint. Для задач Microsoft 365 усе гэтыя варыянты ўжо не викорыстоўваюцца. Graph прыймае толькі OAuth 2.0 через Microsoft Entra ID. Гэта дае можлівасць атрымліваць токены, выкарыстоўваць адну модэль дазволаў і матыць адну пазычную пункт для перагляду таго, хто можа выйсці да якіх дадзенняў. Аднае з выгод — павышэнне безпекі, а не толькі для разработчыкаў — кращая API.

Запыты і групаванне

Адзін запыт Graph, падобны таму, што паказана нижэй, можа фільтруваць, адсікаты і пагрупавляць паведамленні за адну поўную перадачу дадзенняў:

GET https://graph.microsoft.com/v1.0/me/messages
    ?$select=subject,receivedDateTime,from
    &$filter=receivedDateTime ge 2026-07-01T00:00:00Z
    &$top=25
    &$orderby=receivedDateTime desc

Працюючы з старэйшымі, менш гнучкімі канцэнтрамі, для атрымання таго ж рэзультата часта патрабуецца калькі званняў або фільтрацыі на стороне кліента. Аднаразу з $batch можна аб’еднаныць да 20 незалежных операцыяў у аднай HTTP-запытцы, спалучаючы чытанне і запіс для абсалютна разных типаў рэсурсаў.

Регулюванне частоты запыткаў

Graph прымее калькольнае ліміты адразу: па аплікацыі для всіх тэнэнтаў, па тэнэнце для всіх аплікацыяў і па аплікацыі ўнутрь аднаго тэнэнта. Фактычныя цыфры разніцяюцца залежна ад службы — паштоўна, файлы, каталогі і чаты Teams кожны маюць свае сае ліміты. Калі вы перакроеце першы ліміт, будзе падана паметка 429 Too Many Requests з атрыбутам Retry-After, які паведамляе, сколькі часу трэба чакаць. Паўстаноўна, у пораўнанні з старымі API, дзе ліміты часта не былі задокументаваны і ўсё трэба было выявляць у рэальным часе, гэта вялікі прыступ уперад. Аднасць — старая, але яшчэ правільная: выкарыстоўваеце $select, каб запрашаць толькі тыя поля, якія вам патрэбны, вялікую прыягоду даеіе групаванне запытоў і дэльта-запыты замест паллінгу, і завжды прымейце увагу да Retry-After, а не прабавайце запыт зноў адразу.

Дзе ўсё ж такі краща выкарыстоўваць не Graph

Graph яшчэ не паводлівае для всіх задач, і дзеякі случаі сапраўды вымагаюць іншага API.

• Дэталізаваная адарбота з сайтамі SharePoint. Полная інформацыя пра рэвалюціі дазволаў, дзеякія операцыі з групамі сайтаў, а таксама часткі керавання типамі кантэнту і схемамі спісаў існуюць толькі ў SharePoint REST пад _api/web/.... У розвітых проектах SharePoint ўседзённыя задачі з файламі, спісамі та драйвамі выкананыя через Graph, а SharePoint REST выкарыстоўваецца толькі для таго, чаго не хапяе.
• Web-часткі SPFx. Сервіс SharePoint Framework уже забезпечвае готавы контэкст SharePoint REST, таму для індывідуальных налашчэнняў унутры сторніцы гэта часта яе простейшы варыянт, хоця тая ж самая web-частка можа таксама вызываць Graph.

За выняткам гэтых спецыфічных случаў, у гэты год новы проект не мае значных тэхнічных прычын пачынацца з адных з старых канцэнтраў на кожную службу, адколі большасць з іх вялікі час яўляюцца неактыўнымі або знаходзяцца на шляху да зняцья.

Як выбраць

Для кожнай новай інтеграцыі ставіце сабе следуючыя пытанні:

1. Це новая версія? Отрымайцеся ад Microsoft Graph. Новыя функцыі спачатку выходзяць там, і гэта ўжо ўсё, у што Microsoft продаўжае інвеставацыі.
2. Чы рэальны прыклад выкарыстоўвае Azure AD Graph, Outlook REST API чы дадаткі SharePoint на адной з базы ACS? Outlook REST і ACS вже перажылі сваю актуальнасць, а Azure AD Graph будзе зняты з аператыўнай падтрымкі 31 ліпня 2026 года. Спрыяйце гэтаму як да справы з высокай прыорітэтам.
3. Чы трэція сторона выкарыстоўвае EWS для роботы з Exchange Online? Microsoft пачне блакаваць такія запыты 1 жоўтня 2026 года. Пачніце пераходзіць на тэрміналы для роботы з паштой і календарем у Graph яшчэ зараз.
4. Чы вам патрэбна функцыя SharePoint, якой яшчо няма ў Graph? Для такога запыту выкарыстоўвайце SharePoint REST, а для всіх іншых — Graph. Адначасова пераканайцеся ў дакументах SharePoint-in-Graph, адколькі спіс недастаткаў стаўшыць усё корачэй.

Для практычна всіх адпаведнае рашэнне вырашваецца за адной правілам: выкорыстоўваць Microsoft Graph, якщо толькі у вас няма конкрэтнай, задокументаванай прычыны не робіць гэтага.

Той самы запит, тады і зараз

Ёсць запит Outlook REST v2.0, які ўжо не викорыстоўваецца, паказаны толькі для параджання:

GET https://outlook.office.com/api/v2.0/me/messages
Authorization: Bearer {token}

З марца 2024 года гэты канцэнтры пасляў адпаведзь на запыт за дапамогай коду HTTP 410 Gone. Версія таго ж запыту у формате Graph выглядае так:

GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,from,receivedDateTime&$top=10
Authorization: Bearer {token}

SharePoint REST, які ўсё яшчэ падтрымваюцца, чытаюць элементы спіса так:

GET https://{tenant}.sharepoint.com/sites/{site}/_api/web/lists/getbytitle('Documents')/items
Authorization: Bearer {token}
Accept: application/json;odata=verbose

Калі Graph падтрымлівае тую ж аператыю, вызов стае такім:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items
Authorization: Bearer {token}

Механізмы HTTP застаўляюцься аднаковымі ў обох періодах. Тое, што даўае Graph, — это адна базовая URL, адна модэль автанацыі і адна прымета JSON, незалежна ад таго, з якім самэй сервісам Microsoft 365 вы насправдзе вярбуецеся.

Міграцыя з старой API

Якщо вы толькі з’ясавалі, што ў вашым тэнанце ўсё ўсё ж залежыць ад API, якое перестае падтрымвалася, перагляньце гэты список:

1. З’ясавайце, што насправдзе яго выкарыстоўвае. Entra прыносіць два рэкамендацыі: „Міграцыя аплікацыяў“ і „Міграцыя прынцыпалаў службы“, якія паказваюць рэальнае выкарыстоўванне Azure AD Graph у вашым тэнанце за апошнія 30 дзён. Гэта значна краща, чым здагадвання на адной лініі з кодам.
2. Ясна прызначыце правыя. Старыя правыя не пераўодзяцца адназначна ў дыапазоны Graph. Карыстаюцеся офіцыяльнымі кансалтаментамі Microsoft па прызначэнню правых, а не прыпускайце, што два дыапазоны з падобнымі назвамі є эквівалентнымі.
3. Пераказаць аутэнтыкацыю на MSAL. Усе, што яшчэ выкарыстоўвае старую бібліятэку аутэнтыкацыі Azure AD (ADAL), павінна працэўваць па адной з аддзельных схем міграцыі, калікве ADAL вже рокі як не падтрымвана.
4. Зменіце SDK-ы, а не толькі URL-ы. Афіцыйныя Graph SDK-ы для .NET, JavaScript і TypeScript, Python, Java, Go і PowerShell самі керуюць групавымымы выклікамі, павторнымыя спробамі і сторінаваннем. Не пішыце ручныя HTTP-запыткі, як толькі не будзе абавязковай прычыны.
5. Будзьце абераглівы з версіяй beta. Якшчэ якая-небудзь функцыя існуе толькі на beta канцэнтры Graph, яе спецыфікацыя можа змяніцца без паведамлення. Або планаваце гэта, або чакайце, пакуль функцыя стане доступной для всіх.
6. Знайдзіце проблемы 429 у тэставанні. Адрабатывайце навантажэння з рэалістычнымі об’ёмамі запыткаў, каб вы зустрэлі меры обмежэння раней, чым гэта зробяць вашы корыстнікі.
7. Запісаўце рэальную дату заканчэння у свой календар і пераканайцеся ў яе збігу з офіцыяльной документацыяй Microsoft прыбліжна за час до таго, як плануеце на яе паслацца. Ція даты вялікімі крокамі зміняліся раней, таму будь-якую дату, яку вы прачытаеце з іншых джэрел, укладаючы ў гэтыя таксонаміі, трэба спрыягаць як тымчасовую.

Graph таксама ўтрымлівае агенты AI

Є ўсё адно ўзгэле, чым поясніваецца падыгранне. Graph стае плоскасцю керування экосістамай агентаў AI Microsoft. У 2026 году Microsoft дадаў тэрміналы Graph для керування агентамі та прыладкамі Microsoft 365 Copilot, ведэння інвентара агентаў і отрымання болей дакладных звітоў пра выкарыстоўванне Copilot, а таксама функцый, прыязначаных для новейшых ліцензый, такіх як Agent 365. Нічога з гэтага няма ў Azure AD Graph, Outlook REST чы EWS, і ніколі не будзе. Якщо ваша організацыя плануе розвіваць можлівасці Copilot чы ствараць сабственных агентаў, то гэта ўсё адно шлях, які ведае толькі да Graph.

Які наступны крокі

На запитанне па заглавлі ёсць досыта чыста адказ у 2026 годзе:

• Пачынаеце ўсё новае на Microsoft 365 або Entra ID? Іспользуйце Microsoft Graph. Не застаўся жадны случай, калі новы проект трэба пачынаць за дапамогою спецыяльнага REST API старага сервіса.
• Падтрымліваеце старэе інтеграцыю? Спыніцеся на табелі статусу вышэй. Якщо ў яе є вясоў з Azure AD Graph, Outlook REST, дадаткамі SharePoint на базе ACS або доступам через EWS трэціх сторон, вы працуеце па канечнай дате, прычаму дзеяныя з гэтых дат прыбліжаюцца дужа быстра.
• У Graph не ёсць адной з можнасцей SharePoint? Для таго адзінага запытку перайдзіце на SharePoint REST, а всё іншае залишыце на Graph.

У 2018 году, калі Microsoft дзеўналі кілька супернікаючых REST-інтерфейсоў паралельна, тэма „REST API чы Graph“ была правамернай тэмай для дыскусій. Сэгодні ж гэта пераважна про процес упорядкування. Кансалідацыя майже завершана, а альтернатывы вымыраюць з часам.