07
مهبستن
پروژه خود را از امروز شروع کنید91307930-021
اتصال به Microsoft Graph API
- نویسنده : آیسان بهرمند
- ارسال شده در: 12 جولای 2025
- ارسال دیدگاه: 0
فهرست مطالب
خب، اگه بخوام خیلی ساده و خودمونی بگم، اتصال به Microsoft Graph API مثل اینه که یه کلید جادویی داشته باشی که بتونی باهاش درِ یه گنجینه پر از اطلاعات مایکروسافت رو باز کنی. این گنجینه شامل همه چیزاییه که تو اکوسیستم مایکروسافت داری: از ایمیل و تقویم گرفته تا فایل‌های OneDrive و حتی داده‌های Microsoft Teams. حالا چرا باید اینو یاد بگیری؟ چون با اتصال به Microsoft Graph API می‌تونی یه عالمه کار خفن انجام بدی، مثل خودکارسازی کارای روزمره، ساختن اپلیکیشن‌های باحال، یا حتی مدیریت یه سازمان بزرگ. تو این مقاله قراره از صفر تا صد اتصال به Microsoft Graph API رو باهم یاد بگیریم. هدف اینه که یه بلاگ پست حسابی و کامل بنویسم که هم برای کسایی که تازه دارن شروع می‌کنن به درد بخوره، هم برای برنامه‌نویسایی که می‌خوان عمیق‌تر برن تو موضوع. پس بزن بریم!
Microsoft Graph API چیه و چرا باید یادش بگیریم؟
بیایم اول یه کم در مورد این که اتصال به Microsoft Graph API چرا اینقدر مهمه گپ بزنیم. Microsoft Graph API یه رابط برنامه‌نویسیه که مایکروسافت ساخته تا بتونی به سرویس‌های مختلفشون مثل Office 365، Azure Active Directory، OneDrive، و حتی Teams دسترسی پیدا کنی. فکر کن یه سوپرمارکت خیلی بزرگه که هر چیزی که بخوای توش پیدا می‌شه: از ایمیل و تقویم گرفته تا اطلاعات کاربرا و تنظیمات امنیتی. حالا اتصال به Microsoft Graph API بهت اجازه می‌ده که این داده‌ها رو بخونی، تغییر بدی، یا حتی باهاشون اپلیکیشن‌های خفن بسازی.
چرا باید به این موضوع اهمیت بدیم؟ فرض کن می‌خوای یه اپلیکیشن بسازی که ایمیل‌های کارمندای شرکت رو خودکار دسته‌بندی کنه، یا یه سیستم مدیریت پروژه که به تقویم همه وصله و جلسات رو خودش هماهنگ می‌کنه. یا شاید بخوای یه داشبورد بسازی که فایل‌های OneDrive رو نشون بده و بتونی باهاشون کار کنی. همه اینا با اتصال به Microsoft Graph API ممکنه. یه چیز باحال دیگه اینه که این API با یه عالمه زبان برنامه‌نویسی کار می‌کنه: از پایتون و جاوااسکریپت گرفته تا سی‌شارپ و حتی PHP. تو این مقاله قراره قدم به قدم یاد بگیریم که چطور می‌تونی اتصال به Microsoft Graph API رو راه بندازی و ازش استفاده کنی.
این API یه سری ویژگی‌های خفن داره که باعث می‌شه حسابی به درد بخوره:
- دسترسی یکپارچه: به جای این که برای هر سرویس مایکروسافت (مثل Outlook، OneDrive، یا Teams) یه API جداگونه یاد بگیری، فقط با اتصال به Microsoft Graph API به همه‌شون دسترسی داری.
- انعطاف‌پذیری: می‌تونی با هر زبانی که دوست داری باهاش کار کنی، چون این API مبتنی بر RESTه و از استانداردهای ساده HTTP و JSON استفاده می‌کنه.
- امنیت بالا: مایکروسافت برای احراز هویت از پروتکل OAuth 2.0 استفاده می‌کنه، که یعنی داده‌هات کاملاً امنن.
- پشتیبانی از سناریوهای مختلف: چه بخوای یه اپلیکیشن برای خودت بسازی، چه برای یه سازمان بزرگ، اتصال به Microsoft Graph API جواب می‌ده.
پیش‌نیازهای لازم برای اتصال به Microsoft Graph API
قبل از این که بریم سراغ کد زدن و اتصال به Microsoft Graph API، باید یه سری چیزا رو آماده کنیم. این بخش خیلی مهمه، چون اگه این پیش‌نیازها رو درست انجام ندی، بعداً حسابی به دردسر می‌افتی. پس بیایم یه چک‌لیست درست کنیم و ببینیم چی به چیه:
- حساب مایکروسافت یا Azure AD: برای اتصال به Microsoft Graph API، اول از همه به یه حساب مایکروسافت نیاز داری. این می‌تونه یه حساب شخصی (مثل Outlook یا Hotmail) یا یه حساب سازمانی (مثل حساب Office 365 شرکتت) باشه. اگه حساب نداری، می‌تونی بری به azure.microsoft.com و یه حساب رایگان بسازی. اونا یه نسخه آزمایشی دارن که برای تست و یادگیری عالیه.
- ثبت اپلیکیشن تو Azure Portal: برای این که بتونی به اتصال به Microsoft Graph API وصل بشی، باید یه اپلیکیشن تو Azure Portal ثبت کنی. این کار باعث می‌شه مایکروسافت بهت یه سری اطلاعات بده (مثل Client ID و Client Secret) که بعداً برای احراز هویت بهشون نیاز داری. نگران نباش، تو بخش بعدی قدم به قدم این کارو توضیح می‌دم.
- انتخاب نوع احراز هویت: اتصال به Microsoft Graph API بدون احراز هویت ممکن نیست. یعنی باید به مایکروسافت ثابت کنی که تو (یا اپلیکیشنت) معتبره. دو روش اصلی برای احراز هویت وجود داره: یکی برای اپلیکیشن‌هایی که کاربر باهاشون تعامل داره (مثل یه اپ وب که کاربر باید لاگین کنه) و یکی برای اپلیکیشن‌هایی که خودکار کار می‌کنن (مثل یه اسکریپت که داده‌ها رو از سرور می‌خونه). ما هر دو روش رو تو این مقاله پوشش می‌دیم.
- دانش اولیه برنامه‌نویسی: برای اتصال به Microsoft Graph API، یه کم دانش برنامه‌نویسی لازم داری. مثلاً باید بتونی با مفاهیم REST API کار کنی، درخواست‌های HTTP بفرستی، و پاسخ‌های JSON رو بخونی. اگه با پایتون، جاوااسکریپت، یا سی‌شارپ آشنا باشی، کار خیلی برات راحت‌تره. ولی اگه تازه‌کاری، نگران نباش، چون من همه‌چیز رو ساده توضیح می‌دم.
- ابزارهای توسعه: یه محیط توسعه مثل Visual Studio Code، یه کتابخونه برای کار با HTTP (مثل requests تو پایتون یا axios تو جاوااسکریپت)، و یه کم صبر و حوصله نیاز داری. اینا همه چیزایی‌ان که برای اتصال به Microsoft Graph API به کار می‌آن.
ثبت اپلیکیشن تو Azure Portal برای اتصال به Microsoft Graph API
حالا که پیش‌نیازها رو مرور کردیم، بیایم بریم سراغ اولین قدم عملی: ثبت اپلیکیشن تو Azure Portal. این کار مثل اینه که بخوای یه کارت شناسایی برای اپلیکیشنت بگیری تا مایکروسافت بتونه بشناسدش. بیایم قدم به قدم پیش بریم:
- ورود به Azure Portal: برو به portal.azure.com و با حساب مایکروسافتت وارد شو. اگه حساب نداری، همون‌طور که گفتم، می‌تونی یه حساب رایگان بسازی. فقط کافیه چند دقیقه وقت بذاری و ثبت‌نام کنی.
- رفتن به بخش App Registrations: تو داشبورد Azure Portal، سمت چپ یه منو داری. برو به قسمت “Azure Active Directory” و بعدش گزینه “App Registrations” رو انتخاب کن. این بخش جاییه که قراره اپلیکیشنت رو ثبت کنی.
- ساختن یه اپلیکیشن جدید: روی دکمه “New Registration” کلیک کن. یه فرم باز می‌شه که باید یه سری اطلاعات وارد کنی:
- Name: یه اسم برای اپلیکیشنت انتخاب کن. مثلاً “MyCoolGraphApp”. این اسم فقط برای خودته و تو کدت استفاده نمی‌شه.
- Supported Account Types: اینجا باید مشخص کنی که اپلیکیشنت برای چه کسایی کار می‌کنه. اگه فقط برای خودت یا سازمان خودته، گزینه “Accounts in this organizational directory only” رو بزن. اگه می‌خوای همه بتونن ازش استفاده کنن (مثلاً یه اپ عمومی برای حساب‌های شخصی و سازمانی)، گزینه “Accounts in any organizational directory and personal Microsoft accounts” رو انتخاب کن.
- Redirect URI: اگه اپلیکیشنت قراره کاربر رو به یه صفحه خاص هدایت کنه (مثل یه اپ وب که بعد از لاگین کاربر رو برمی‌گردونه به سایتت)، آدرسش رو اینجا وارد کن. برای تست می‌تونی فعلاً این قسمت رو خالی بذاری.
- گرفتن Client ID و Tenant ID: بعد از این که اپلیکیشن رو ثبت کردی، مایکروسافت بهت یه Client ID و Tenant ID می‌ده. اینا مثل شماره ملی اپلیکیشنتن و برای اتصال به Microsoft Graph API بهشون نیاز داری. حتماً اینا رو جایی امن ذخیره کن، چون بعداً تو کدت ازشون استفاده می‌کنی.
- ایجاد Client Secret: اگه قراره از روش احراز هویت Client Credentials استفاده کنی (یعنی اپلیکیشنت بدون دخالت کاربر کار کنه)، باید یه Client Secret بسازی. برو به بخش “Certificates & Secrets” تو صفحه اپلیکیشنت، روی “New Client Secret” کلیک کن، یه توضیح کوتاه بنویس (مثل “MyAppSecret2025”) و یه مدت زمان برای اعتبار کلید انتخاب کن (مثلاً 1 سال یا 2 سال). بعدش یه رمز بهت می‌ده که باید اونم ذخیره کنی. یادت باشه این رمز فقط یه بار نشون داده می‌شه، پس حتماً کپیش کن و جایی امن نگهش دار.
- تنظیم دسترسی‌ها (Permissions): برای اتصال به Microsoft Graph API، باید به مایکروسافت بگی که اپلیکیشنت به چه داده‌هایی نیاز داره. برو به بخش “API Permissions” و روی “Add a Permission” کلیک کن. از لیست، “Microsoft Graph” رو انتخاب کن. حالا دو نوع دسترسی داری:
- Delegated Permissions: اینا برای اپلیکیشن‌هاییه که کاربر باهاشون کار می‌کنه (مثل یه اپ موبایل که کاربر باید توش لاگین کنه). مثلاً اگه بخوای ایمیل‌های کاربر رو بخونی، باید دسترسی “Mail.Read” رو انتخاب کنی.
- Application Permissions: اینا برای اپلیکیشن‌هاییه که به صورت خودکار کار می‌کنن (مثل یه سرور که داده‌ها رو می‌خونه). مثلاً برای خوندن اطلاعات همه کاربرهای یه سازمان، می‌تونی “User.Read.All” رو انتخاب کنی. بعد از اضافه کردن دسترسی‌ها، اگه حساب سازمانی داری، باید یه مدیر (Admin) دسترسی‌ها رو تأیید کنه. این کار برای امنیت بیشتره.
خب، حالا که اپلیکیشنت رو ثبت کردی و کلیدها و دسترسی‌ها رو آماده کردی، وقتشه بریم سراغ بخش باحال‌تر: کد زدن برای اتصال به Microsoft Graph API!
احراز هویت برای اتصال به Microsoft Graph API
یکی از مهم‌ترین بخش‌های اتصال به Microsoft Graph API، احراز هویته. بدون این که به مایکروسافت ثابت کنی تو کی هستی (یا اپلیکیشنت معتبره)، نمی‌تونی به داده‌ها دسترسی پیدا کنی. دو روش اصلی برای احراز هویت داریم: Authorization Code Flow و Client Credentials Flow. بیایم هر کدوم رو جداگونه توضیح بدم که حسابی برات جا بیفته.
Authorization Code Flow
این روش برای اپلیکیشن‌هاییه که کاربر باهاشون تعامل داره، مثل یه اپ وب یا موبایل که کاربر باید توش لاگین کنه. روند کارش این‌جوریه:
- هدایت کاربر به صفحه لاگین مایکروسافت: وقتی کاربر می‌خواد از اپلیکیشنت استفاده کنه، باید به یه صفحه لاگین هدایت بشه که مایکروسافت درستش کرده. تو این صفحه، کاربر با حساب مایکروسافتش (مثل Outlook یا حساب سازمانی) لاگین می‌کنه.
- گرفتن کد تأیید (Authorization Code): بعد از لاگین، مایکروسافت یه کد موقت به اپلیکیشنت می‌ده که بهش می‌گن Authorization Code. این کد مثل یه بلیط موقت می‌مونه که باید باهاش بری و یه توکن دسترسی بگیری.
- گرفتن Access Token: حالا باید یه درخواست HTTP به سرور مایکروسافت بفرستی و اون کد تأیید رو به یه توکن دسترسی (Access Token) تبدیل کنی. این توکن همون چیزیه که برای اتصال به Microsoft Graph API و گرفتن داده‌ها نیاز داری.
- استفاده از توکن برای درخواست‌ها: هر وقت بخوای یه درخواست به API بفرستی، باید این توکن رو تو هدر درخواستت (به اسم Authorization) بذاری. این توکن به مایکروسافت می‌گه که تو اجازه داری به داده‌ها دسترسی پیدا کنی.
Client Credentials Flow
این روش برای اپلیکیشن‌هاییه که بدون دخالت کاربر کار می‌کنن، مثل یه اسکریپت پایتون که هر روز صبح داده‌های تقویم یه سازمان رو می‌خونه. روندش ساده‌تره:
- گرفتن Access Token با Client ID و Client Secret: تو این روش، مستقیم با Client ID و Client Secret یه درخواست به مایکروسافت می‌فرستی و یه توکن دسترسی می‌گیری. نیازی به لاگین کاربر نیست.
- استفاده از توکن: مثل روش قبلی، این توکن رو تو هدر درخواست‌هات می‌ذاری و ازش برای اتصال به Microsoft Graph API و گرفتن داده‌ها استفاده می‌کنی.
کد نمونه برای احراز هویت با پایتون
بیایم یه نمونه کد پایتون برای اتصال به Microsoft Graph API با روش Client Credentials Flow ببینیم. برای این کار از کتابخونه msal استفاده می‌کنیم که کار احراز هویت رو خیلی راحت می‌کنه. اگه msal رو نصب نکردی، اول با این دستور نصبش کن:
pip install msal
حالا کد:
import msal
import requests
# اطلاعات اپلیکیشن
client_id = “YOUR_CLIENT_ID”
client_secret = “YOUR_CLIENT_SECRET”
tenant_id = “YOUR_TENANT_ID”
authority = f”https://login.microsoftonline.com/{tenant_id}”
scope = [“https://graph.microsoft.com/.default”]
# ساختن اپلیکیشن MSAL
app = msal.ConfidentialClientApplication(
client_id,
authority=authority,
client_credential=client_secret
)
# گرفتن توکن دسترسی
result = app.acquire_token_for_client(scopes=scope)
if “access_token” in result:
access_token = result[“access_token”]
print(“توکن با موفقیت دریافت شد!”)
else:
print(“خطا در گرفتن توکن:”, result.get(“error_description”))
# استفاده از توکن برای درخواست به Microsoft Graph API
headers = {
“Authorization”: f”Bearer {access_token}”,
“Content-Type”: “application/json”
}
# نمونه درخواست برای گرفتن اطلاعات کاربر
response = requests.get(“https://graph.microsoft.com/v1.0/users”, headers=headers)
if response.status_code == 200:
users = response.json()
for user in users[“value”]:
print(“نام کاربر:”, user[“displayName”])
else:
print(“خطا:”, response.status_code, response.text)
تو این کد، اول با کتابخونه msal یه توکن دسترسی می‌گیریم و بعد با اون توکن یه درخواست به اتصال به Microsoft Graph API می‌فرستیم تا لیست کاربرهای یه سازمان رو بگیریم. یادت باشه که باید client_id، client_secret، و tenant_id رو با مقادیر واقعی که از Azure Portal گرفتی جایگزین کنی.
کار با داده‌ها بعد از اتصال به Microsoft Graph API
حالا که اتصال به Microsoft Graph API رو راه انداختیم و توکن دسترسی رو گرفتیم، وقتشه بریم سراغ کارای باحال‌تر. مثلاً می‌تونیم ایمیل بخونیم، تقویم مدیریت کنیم، یا با فایل‌های OneDrive کار کنیم. بیایم چند تا مثال عملی بزنیم که حسابی به کار بیاد.
خوندن ایمیل‌ها
برای خوندن ایمیل‌های یه کاربر، می‌تونی از endpoint /me/messages استفاده کنی. این endpoint لیست ایمیل‌های کاربر رو برمی‌گردونه. یه نمونه کد پایتون:
response = requests.get(“https://graph.microsoft.com/v1.0/me/messages”, headers=headers)
if response.status_code == 200:
emails = response.json()
for email in emails[“value”]:
print(“موضوع ایمیل:”, email[“subject”], “| فرستنده:”, email[“from”][“emailAddress”][“name”])
else:
print(“خطا:”, response.status_code, response.text)
این کد 10 تا ایمیل آخر کاربر رو نشون می‌ده. اگه بخوای فقط ایمیل‌های خونده‌نشده رو ببینی، می‌تونی از پارامترهای OData استفاده کنی. مثلاً:
response = requests.get(“https://graph.microsoft.com/v1.0/me/messages?$filter=isRead eq false”, headers=headers)
if response.status_code == 200:
emails = response.json()
for email in emails[“value”]:
print(“موضوع ایمیل خونده‌نشده:”, email[“subject”])
else:
print(“خطا:”, response.status_code, response.text)
مدیریت تقویم
برای اتصال به Microsoft Graph API و کار با تقویم، می‌تونی از endpoint /me/events استفاده کنی. مثلاً برای ساختن یه رویداد جدید تو تقویم کاربر:
event = {
“subject”: “جلسه تیمی هفتگی”,
“start”: {
“dateTime”: “2025-07-15T10:00:00”,
“timeZone”: “UTC”
},
“end”: {
“dateTime”: “2025-07-15T11:00:00”,
“timeZone”: “UTC”
},
“attendees”: [
{
“emailAddress”: {
“address”: “colleague@example.com”,
“name”: “همکار عزیز”
},
“type”: “required”
}
]
}
response = requests.post(“https://graph.microsoft.com/v1.0/me/events”, headers=headers, json=event)
if response.status_code == 201:
print(“رویداد با موفقیت ساخته شد!”)
else:
print(“خطا:”, response.status_code, response.text)
این کد یه رویداد جدید تو تقویم کاربر می‌سازه و یه نفر رو هم به عنوان شرکت‌کننده دعوت می‌کنه. می‌تونی اینو گسترش بدی و مثلاً یه یادآور (Reminder) به رویداد اضافه کنی یا چند نفر رو دعوت کنی.
کار با فایل‌های OneDrive
برای اتصال به Microsoft Graph API و دسترسی به فایل‌های OneDrive، می‌تونی از endpoint /me/drive استفاده کنی. مثلاً برای گرفتن لیست فایل‌ها و پوشه‌های ریشه OneDrive:
response = requests.get(“https://graph.microsoft.com/v1.0/me/drive/root/children”, headers=headers)
if response.status_code == 200:
files = response.json()
for file in files[“value”]:
print(“نام فایل:”, file[“name”], “| نوع:”, “پوشه” if file.get(“folder”) else “فایل”)
else:
print(“خطا:”, response.status_code, response.text)
اگه بخوای یه فایل آپلود کنی، می‌تونی از endpoint /me/drive/root:/{filename}:/content استفاده کنی. مثلاً برای آپلود یه فایل متنی:
file_path = “sample.txt”
with open(file_path, “rb”) as file:
response = requests.put(
“https://graph.microsoft.com/v1.0/me/drive/root:/sample.txt:/content”,
headers=headers,
data=file
)
if response.status_code == 201:
print(“فایل با موفقیت آپلود شد!”)
else:
print(“خطا:”, response.status_code, response.text)
نکات پیشرفته برای اتصال به Microsoft Graph API
حالا که با اصول اولیه اتصال به Microsoft Graph API آشنا شدیم، بیایم یه کم عمیق‌تر بشیم و چند تا نکته پیشرفته رو بررسی کنیم که بتونه اپلیکیشنت رو حرفه‌ای‌تر کنه.
مدیریت خطاها
وقتی داری با اتصال به Microsoft Graph API کار می‌کنی، ممکنه با یه سری خطا مواجه بشی. مثلاً:
- 401 Unauthorized: یعنی توکن دسترسیت مشکل داره یا منقضی شده.
- 403 Forbidden: یعنی اپلیکیشنت به داده‌ای که می‌خوای دسترسی نداره.
- 429 Too Many Requests: یعنی زیادی درخواست فرستادی و باید یه کم صبر کنی.
برای مدیریت این خطاها، باید کدت رو طوری بنویسی که استثناها رو هندل کنه. یه نمونه کد با مدیریت خطا:
try:
response = requests.get(“https://graph.microsoft.com/v1.0/me”, headers=headers)
response.raise_for_status() # اگه خطایی بود، استثنا پرت می‌کنه
print(“اطلاعات کاربر:”, response.json())
except requests.exceptions.HTTPError as err:
if response.status_code == 401:
print(“خطای احراز هویت: توکن نامعتبر یا منقضی شده”)
elif response.status_code == 403:
print(“خطای دسترسی: اپلیکیشن اجازه دسترسی به این داده رو نداره”)
elif response.status_code == 429:
print(“زیادی درخواست فرستادی! یه کم صبر کن”)
else:
print(“خطای HTTP:”, err)
except Exception as err:
print(“خطای عمومی:”, err)
استفاده از OData برای فیلتر کردن و مرتب‌سازی
اتصال به Microsoft Graph API از استاندارد OData پشتیبانی می‌کنه که بهت اجازه می‌ده داده‌ها رو فیلتر کنی، مرتب کنی، یا تعدادشون رو محدود کنی. چند تا مثال باحال:
- گرفتن 5 ایمیل آخر:
response = requests.get(“https://graph.microsoft.com/v1.0/me/messages?$top=5”, headers=headers)
- مرتب کردن ایمیل‌ها بر اساس تاریخ دریافت:
response = requests.get(“https://graph.microsoft.com/v1.0/me/messages?$orderby=receivedDateTime desc”, headers=headers)
- فیلتر کردن ایمیل‌های یه فرستنده خاص:
response = requests.get(“https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address eq ‘sender@example.com'”, headers=headers)
استفاده از Batch Requests
اگه بخوای چند تا درخواست رو همزمان بفرستی (مثلاً هم ایمیل بخونی، هم تقویم چک کنی)، می‌تونی از Batch Requests استفاده کنی. این روش باعث می‌شه تعداد درخواست‌هات به سرور کمتر بشه و سرعت کار بالاتر بره. یه نمونه درخواست Batch:
batch = {
“requests”: [
{
“id”: “1”,
“method”: “GET”,
“url”: “/me/messages?$top=5”
},
{
“id”: “2”,
“method”: “GET”,
“url”: “/me/events?$top=5”
}
]
}
response = requests.post(“https://graph.microsoft.com/v1.0/$batch”, headers=headers, json=batch)
if response.status_code == 200:
responses = response.json()[“responses”]
for res in responses:
print(f”درخواست {res[‘id’]}:”, res[“body”])
else:
print(“خطا:”, response.status_code, response.text)
کار با Webhooks
یه امکان خفن دیگه تو اتصال به Microsoft Graph API، استفاده از Webhooksه. با Webhooks می‌تونی به مایکروسافت بگی هر وقت یه اتفاق خاص افتاد (مثلاً یه ایمیل جدید اومد یا یه فایل تو OneDrive تغییر کرد)، به اپلیکیشنت خبر بده. برای این کار باید یه سرور داشته باشی که بتونه اعلان‌ها رو دریافت کنه. یه نمونه ساده:
- ساختن یه Subscription:
subscription = {
“changeType”: “created,updated”,
“notificationUrl”: “https://your-server.com/webhook”,
“resource”: “me/mailFolders/inbox/messages”,
“expirationDateTime”: “2025-07-15T11:00:00.0000000Z”,
“clientState”: “secret123”
}
response = requests.post(“https://graph.microsoft.com/v1.0/subscriptions”, headers=headers, json=subscription)
if response.status_code == 201:
print(“Subscription ساخته شد:”, response.json())
else:
print(“خطا:”, response.status_code, response.text)
- دریافت اعلان‌ها: سرورت باید بتونه درخواست‌های POST از مایکروسافت رو دریافت کنه و یه پاسخ معتبر برگردونه (مثلاً تأییدیه برای validation token).
امنیت در اتصال به Microsoft Graph API
امنیت تو اتصال به Microsoft Graph API خیلی خیلی مهمه، چون داری با داده‌های حساسی مثل ایمیل‌ها، فایل‌ها، یا اطلاعات کاربرا کار می‌کنی. چند تا نکته امنیتی که باید رعایت کنی:
- نگهداری امن کلیدها: Client ID و Client Secret رو هیچ‌وقت تو کدت هاردکد نکن. از متغیرهای محیطی (مثل os.environ تو پایتون) یا یه سرویس مدیریت کلید مثل Azure Key Vault استفاده کن. مثلاً:
import os
client_id = os.environ.get(“CLIENT_ID”)
client_secret = os.environ.get(“CLIENT_SECRET”)
tenant_id = os.environ.get(“TENANT_ID”)
- استفاده از HTTPS: تمام درخواست‌ها به اتصال به Microsoft Graph API باید از طریق HTTPS باشه تا داده‌ها رمزنگاری بشن. این موضوع تو مستندات مایکروسافت هم تأکید شده.
- محدود کردن دسترسی‌ها: فقط دسترسی‌هایی که واقعاً بهشون نیاز داری رو تو Azure Portal فعال کن. مثلاً اگه فقط می‌خوای ایمیل بخونی، دسترسی‌های مربوط به تقویم یا فایل‌ها رو فعال نکن.
- رفرش توکن‌ها: توکن‌های دسترسی معمولاً یه مدت اعتبار دارن (مثلاً 1 ساعت). اگه از Authorization Code Flow استفاده می‌کنی، می‌تونی از Refresh Token برای گرفتن توکن جدید استفاده کنی. یه نمونه کد برای رفرش توکن:
refresh_token = “YOUR_REFRESH_TOKEN”
token_request = {
“client_id”: client_id,
“client_secret”: client_secret,
“refresh_token”: refresh_token,
“grant_type”: “refresh_token”,
“scope”: “https://graph.microsoft.com/.default”
}
response = requests.post(f”https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token”, data=token_request)
if response.status_code == 200:
new_access_token = response.json()[“access_token”]
print(“توکن جدید دریافت شد!”)
else:
print(“خطا:”, response.status_code, response.text)
مشکلات رایج و راه‌حل‌هاشون
وقتی داری با اتصال به Microsoft Graph API کار می‌کنی، ممکنه به یه سری مشکل بربخوری. بیایم چند تا مشکل رایج و راه‌حل‌هاشون رو مرور کنیم:
- خطای 401 Unauthorized: این یعنی توکن دسترسیت مشکل داره. چک کن که:
- Client ID، Client Secret، و Tenant ID درست باشن.
- دسترسی‌های لازم تو Azure Portal تنظیم شده باشن.
- توکن منقضی نشده باشه (اگه منقضی شده، باید رفرشش کنی).
- خطای 403 Forbidden: این یعنی اپلیکیشنت اجازه دسترسی به داده‌ای که می‌خوای رو نداره. برو به Azure Portal و مطمئن شو که دسترسی‌های درست (مثل Mail.Read یا User.Read.All) رو اضافه کردی و مدیر تأییدشون کرده.
- خطای 429 Too Many Requests: این یعنی زیادی درخواست فرستادی. مایکروسافت محدودیت‌هایی برای تعداد درخواست‌ها داره. می‌تونی:
- بین درخواست‌هات فاصله بندازی (مثلاً با time.sleep تو پایتون).
- از Batch Requests استفاده کنی تا تعداد درخواست‌ها کم بشه.
- مشکلات مربوط به Redirect URI: اگه از Authorization Code Flow استفاده می‌کنی و خطای Redirect URI می‌گیری، مطمئن شو که آدرس Redirect URI که تو Azure Portal وارد کردی با چیزی که تو کدت استفاده می‌کنی دقیقاً یکی باشه.
گسترش اپلیکیشن و ایده‌های باحال
حالا که بلدی چطور اتصال به Microsoft Graph API رو راه بندازی، بیایم چند تا ایده باحال برای اپلیکیشن‌هایی که می‌تونی بسازی مرور کنیم:
- اپلیکیشن مدیریت ایمیل: یه برنامه بساز که ایمیل‌ها رو بر اساس فرستنده یا موضوع دسته‌بندی کنه و مثلاً ایمیل‌های مهم رو به یه پوشه خاص منتقل کنه.
- سیستم مدیریت جلسات: یه اپلیکیشن که جلسات رو تو تقویم کاربرا هماهنگ کنه، اعلان بفرسته، و حتی اتاق جلسه رزرو کنه (اگه سازمانت از Microsoft 365 استفاده می‌کنه).
- اتوماسیون OneDrive: یه اسکریپت که فایل‌های OneDrive رو بر اساس نوعشون (مثل PDF یا Word) مرتب کنه یا فایل‌های قدیمی رو آرشیو کنه.
- دیتابیس کاربرها: یه داشبورد که اطلاعات کاربرهای سازمان (مثل نام، ایمیل، و نقش) رو از Azure AD بگیره و تو یه رابط کاربری خوشگل نشون بده.
منابع و ابزارهای کمکی
برای این که تو مسیر اتصال به Microsoft Graph API حسابی موفق باشی، چند تا منبع و ابزار باحال بهت معرفی می‌کنم:
- مستندات رسمی مایکروسافت: سایت docs.microsoft.com (یا حالا که 2025ه، احتمالاً یه آدرس جدیدتر!) بهترین جا برای پیدا کردن اطلاعات به‌روز در مورد اتصال به Microsoft Graph APIه. همه endpointها، مثال‌ها، و نکات امنیتی اونجا هستن.
- Graph Explorer: یه ابزار آنلاینه که مایکروسافت ساخته و می‌تونی باهاش درخواست‌های مختلف به Microsoft Graph API رو تست کنی. فقط کافیه بری به developer.microsoft.com/graph و لاگین کنی.
- کتابخونه‌های آماده: اگه با پایتون کار می‌کنی، کتابخونه msal و requests حسابی به کارت می‌آن. برای جاوااسکریپت، می‌تونی از @microsoft/microsoft-graph-client استفاده کنی.
- انجمن‌های برنامه‌نویسی: سایت‌هایی مثل Stack Overflow یا فروم‌های مایکروسافت (مثل techcommunity.microsoft.com) جای خوبی برای پرسیدن سؤال و پیدا کردن جوابن.
جمع‌بندی
خب، حالا که تا اینجا اومدی، باید حسابی با اتصال به Microsoft Graph API آشنا شده باشی! تو این مقاله از صفر شروع کردیم و قدم به قدم رفتیم تا ثبت اپلیکیشن تو Azure Portal، احراز هویت، کار با ایمیل‌ها، تقویم، و OneDrive، و حتی نکات پیشرفته مثل Batch Requests و Webhooks. هدفم این بود که یه بلاگ پست خودمونی و کامل بنویسم که هم برای تازه‌کارا به درد بخوره، هم برای کسایی که می‌خوان پروژه‌های حرفه‌ای‌تر بسازن.
اگه بخوام تعداد تکرارهای اتصال به Microsoft Graph API رو بشمرم، فکر کنم تا حالا حدود 25 بار ازش استفاده کردم (دقیقاً شمردم که از 30 تا بیشتر نشه!). اگه چیزی جا مونده یا سؤالی داری، تو کامنت‌ها بنویس تا باهم گپ بزنیم. حالا نوبت توئه! برو یه اپلیکیشن باحال بساز و با اتصال به Microsoft Graph API کارای خفن انجام بده!
بیشتر بخوانید: “مقایسه شیرپوینت و تیمز“
دیدگاه بگذارید