خب، حالا که پیش‌نیازها رو آماده کردیم، بیایم بریم سراغ روش‌های مختلف برای اتصال به SPOService. این سرویس خیلی انعطاف‌پذیره و بسته به نیازت، می‌تونی از چند روش مختلف برای وصل شدن بهش استفاده کنی. من اینجا سه روش اصلی رو توضیح می‌دم: استفاده از CSOM، استفاده از REST API و استفاده از Microsoft Graph API. هر کدوم از این روش‌ها مزایا و معایب خودشون رو دارن، و من قراره بگم کدومشون برای چه کاری مناسب‌تره.

1. اتصال به SPOService با CSOM

اولین روشی که قراره باهم بررسی کنیم، استفاده از Client-Side Object Model یا همون CSOMه. این روش بیشتر برای کسایی مناسبه که با زبان‌هایی مثل C# کار می‌کنن و می‌خوان یه کنترل دقیق روی SharePoint داشته باشن. CSOM یه کتابخونه‌ست که مایکروسافت برای کار با SharePoint Online ارائه کرده. با این کتابخونه می‌تونی تقریباً هر کاری که تو SharePoint می‌شه انجام داد رو از طریق کد انجام بدی، از آپلود فایل گرفته تا مدیریت کاربران و مجوزها.

برای شروع، باید پکیج Microsoft.SharePointOnline.CSOM رو از NuGet نصب کنی. اگه با Visual Studio کار می‌کنی، کافیه بری تو NuGet Package Manager و این پکیج رو سرچ کنی و نصبش کنی. بعدش باید یه نمونه از ClientContext بسازی که در واقع دروازه ورودت به SharePointه. یه کد ساده برای اتصال به SPOService با CSOM این شکلیه:

using Microsoft.SharePoint.Client;
using System.Security;

string siteUrl = "https://yourtenant.sharepoint.com/sites/yoursite";
string userName = "yourusername@yourtenant.com";
string password = "yourpassword";

using (var context = new ClientContext(siteUrl))
{
    var securePassword = new SecureString();
    foreach (char c in password)
    {
        securePassword.AppendChar(c);
    }
    context.Credentials = new SharePointOnlineCredentials(userName, securePassword);
    context.ExecuteQuery();
    Console.WriteLine("اتصال به SPOService با موفقیت انجام شد!");
}

تو این کد، ما داریم با نام کاربری و رمز عبور به یه سایت SharePoint وصل می‌شیم. فقط حواستون باشه که این روش (استفاده از نام کاربری و رمز) یه روش قدیمیه و ممکنه تو بعضی سازمان‌ها غیرفعال باشه، چون مایکروسافت داره به سمت احراز هویت مدرن (مثل OAuth) می‌ره. اگه بخوای از OAuth استفاده کنی، باید یه اپلیکیشن تو Azure AD ثبت کنی و از Client ID و Client Secret استفاده کنی. من تو بخش بعدی این روش رو مفصل توضیح می‌دم.

یه نکته مهم درباره CSOM اینه که خیلی قدرتمنده، ولی یه کم پیچیده‌ست. مثلاً اگه بخوای یه لیست رو بخونی یا یه فایل آپلود کنی، باید با مفاهیم مثل ListItem، File و Folder آشنا باشی. یه مثال دیگه برات می‌زنم که نشون می‌ده چطور می‌تونی یه فایل رو تو یه لایبرری آپلود کنی:

using (var context = new ClientContext(siteUrl))
{
    context.Credentials = new SharePointOnlineCredentials(userName, securePassword);
    var web = context.Web;
    var library = web.Lists.GetByTitle("Documents");
    var filePath = @"C:\path\to\your\file.txt";
    var fileContent = System.IO.File.ReadAllBytes(filePath);
    var fileCreationInfo = new FileCreationInformation
    {
        Content = fileContent,
        Url = "file.txt",
        Overwrite = true
    };
    var uploadedFile = library.RootFolder.Files.Add(fileCreationInfo);
    context.ExecuteQuery();
    Console.WriteLine("فایل با موفقیت آپلود شد!");
}

این کد یه فایل رو تو لایبرری “Documents” آپلود می‌کنه. حالا اگه بخوای یه لیست رو بخونی یا یه آیتم جدید اضافه کنی، فقط کافیه با ساختارهای CSOM آشنا باشی. من تو بخش‌های بعدی چندتا مثال عملی دیگه برات می‌زنم که بتونی حسابی دستت بیاد.

2. اتصال به SPOService با REST API

روش دوم برای اتصال به SPOService، استفاده از REST APIه. این روش برای کسایی مناسبه که می‌خوان با زبان‌های مختلف (مثل پایتون، جاوااسکریپت یا حتی PHP) به SharePoint وصل بشن. REST API یه رابط سبک و ساده‌ست که از درخواست‌های HTTP (مثل GET، POST، PUT و DELETE) استفاده می‌کنه. مزیتش اینه که خیلی انعطاف‌پذیره و می‌تونی تو هر محیطی ازش استفاده کنی.

برای استفاده از REST API، باید یه سری endpointهای خاص رو بشناسی. مثلاً برای گرفتن لیست‌های یه سایت، می‌تونی از این endpoint استفاده کنی:

https://yourtenant.sharepoint.com/sites/yoursite/_api/web/lists

برای اتصال به SPOService با REST API، معمولاً از OAuth 2.0 برای احراز هویت استفاده می‌شه. اول باید یه اپلیکیشن تو Azure AD ثبت کنی و یه Client ID و Client Secret بگیری. بعدش می‌تونی با یه ابزار مثل Postman یا یه کتابخونه مثل requests تو پایتون، درخواست بفرستی. یه مثال ساده با پایتون:

import requests
from msal import ConfidentialClientApplication

tenant_id = "your-tenant-id"
client_id = "your-client-id"
client_secret = "your-client-secret"
site_url = "https://yourtenant.sharepoint.com/sites/yoursite"
authority = f"https://login.microsoftonline.com/{tenant_id}"
scope = ["https://graph.microsoft.com/.default"]

app = ConfidentialClientApplication(client_id, authority=authority, client_credential=client_secret)
result = app.acquire_token_for_client(scopes=scope)

if "access_token" in result:
    headers = {
        "Authorization": f"Bearer {result['access_token']}",
        "Accept": "application/json;odata=verbose"
    }
    response = requests.get(f"{site_url}/_api/web/lists", headers=headers)
    print("اتصال به SPOService برقرار شد!")
    print(response.json())
else:
    print("خطا در احراز هویت!")

تو این کد، ما داریم با استفاده از کتابخونه msal تو پایتون، یه توکن دسترسی می‌گیریم و بعد با اون توکن، یه درخواست به REST API می‌فرستیم. این روش خیلی تمیزه و برای پروژه‌هایی که نیاز به ادغام سریع دارن، عالیه. فقط باید حواست به مدیریت توکن‌ها باشه، چون توکن‌های OAuth معمولاً یه مدت اعتبار دارن و بعدش منقضی می‌شن.

3. اتصال به SPOService با Microsoft Graph API

روش سوم که یه کم جدیدتره، استفاده از Microsoft Graph APIه. این API در واقع یه لایه بالاتر از REST API خود SharePointه و بهت اجازه می‌ده نه‌تنها با SharePoint، بلکه با بقیه سرویس‌های Microsoft 365 (مثل Teams، OneDrive و Outlook) هم کار کنی. اگه پروژه‌ات یه جورایی به چند سرویس مایکروسافت وصل می‌شه، این روش بهترین گزینه‌ست.

برای اتصال به SPOService با Graph API، باز هم نیاز به احراز هویت با Azure AD داری. یه مثال ساده با Pthon:

import requests
from msal import ConfidentialClientApplication

tenant_id = "your-tenant-id"
client_id = "your-client-id"
client_secret = "your-client-secret"
authority = f"https://login.microsoftonline.com/{tenant_id}"
scope = ["https://graph.microsoft.com/.default"]

app = ConfidentialClientApplication(client_id, authority=authority, client_credential=client_secret)
result = app.acquire_token_for_client(scopes=scope)

if "access_token" in result:
    headers = {
        "Authorization": f"Bearer {result['access_token']}",
        "Accept": "application/json"
    }
    response = requests.get("https://graph.microsoft.com/v1.0/sites/yourtenant.sharepoint.com:/sites/yoursite:/lists", headers=headers)
    print("اتصال به SPOService با Graph API برقرار شد!")
    print(response.json())
else:
    print("خطا در احراز هویت!")

این کد خیلی شبیه به مثال REST APIه، ولی endpointها فرق دارن. Graph API یه ساختار یکپارچه‌تر داره و کار باهاش یه کم راحت‌تره، چون مستنداتش خیلی مرتب و منظمه. فقط باید حواست به permissionهای لازم باشه. مثلاً برای خوندن لیست‌ها، باید دسترسی Sites.Read.All رو تو Azure AD تنظیم کنی.