راهنمای توسعه دهنده: دات نت

مهم : پشتیبانی از API Google Data v2.0 را در 30 سپتامبر 2024 متوقف خواهیم کرد. برای اطمینان از ادامه عملکرد، برنامه‌های کاربردی خود را که به API Google Data v2.0 متکی هستند به آخرین نسخه API به‌روزرسانی کنید. برای آخرین نسخه، از پیوندهای موجود در نوار ناوبری سمت چپ استفاده کنید. توجه: در حالی که برخی از درخواست‌های GET (مانند پست‌های فهرست‌بندی) همچنان به عنوان URL فید پشتیبانی می‌شوند، تفاوت‌های جزئی در رفتار آنها وجود دارد. برای اطلاعات دقیق، به مستندات راهنمای Blogger مراجعه کنید.

Blogger Data API به برنامه های مشتری اجازه می دهد تا محتوای Blogger را در قالب فیدهای Google Data API مشاهده و به روز کنند.

برنامه مشتری شما می تواند از Blogger Data API برای ایجاد پست های وبلاگ جدید، ویرایش یا حذف پست های وبلاگ موجود و پرس و جو برای پست های وبلاگی که با معیارهای خاصی مطابقت دارند استفاده کند.

این سند علاوه بر ارائه پیش‌زمینه‌ای در مورد قابلیت‌های Blogger Data API، نمونه‌هایی از تعاملات پایه داده API را با استفاده از کتابخانه سرویس گیرنده دات‌نت ارائه می‌کند. اگر علاقه مند به درک بیشتر در مورد پروتکل اساسی که کتابخانه استفاده می کند، به بخش پروتکل این راهنمای توسعه دهنده مراجعه کنید.

مطالب

  1. مخاطب
  2. شروع کردن
    1. ایجاد حساب بلاگر
    2. اجرای کد نمونه
  3. احراز هویت در سرویس بلاگر
    1. احراز هویت پروکسی AuthSub
    2. احراز هویت نام کاربری/گذرواژه ClientLogin
  4. بازیابی لیستی از وبلاگ ها
  5. ایجاد پست ها
    1. انتشار پست وبلاگ
    2. ایجاد پیش نویس پست وبلاگ
  6. در حال بازیابی پست ها
    1. بازیابی همه پست های وبلاگ
    2. بازیابی پست ها با استفاده از پارامترهای پرس و جو
  7. به روز رسانی پست ها
  8. حذف پست ها
  9. نظرات
    1. ایجاد نظرات
    2. بازیابی نظرات
    3. حذف نظرات

مخاطب

این سند برای برنامه نویسانی در نظر گرفته شده است که می خواهند برنامه های کلاینت دات نت بنویسند که می توانند با بلاگر تعامل داشته باشند.

این سند فرض می‌کند که شما ایده‌های کلی پشت پروتکل Google Data APIs را درک می‌کنید.

برای اطلاعات مرجع در مورد کلاس ها و روش های ارائه شده توسط کتابخانه سرویس گیرنده، به مرجع API کتابخانه کلاینت دات نت مراجعه کنید. برای اطلاعات عمومی مرجع Blogger Data API، به راهنمای مرجع پروتکل مراجعه کنید.

شروع کردن

برای راهنمایی در تنظیم کتابخانه سرویس گیرنده، به راهنمای شروع مراجعه کنید.

برای استفاده از کتابخانه کلاینت دات نت، به زمان اجرا .NET 1.1 نیاز دارید، و همچنین باید در تمام وصله ها به روز باشید. پس از دانلود کتابخانه سرویس گیرنده ، DLL هایی را که برای شروع به کار نیاز دارید، در زیر شاخه lib/Release توزیع پیدا خواهید کرد.

ایجاد حساب بلاگر

ممکن است بخواهید برای اهداف آزمایشی برای یک حساب Blogger ثبت نام کنید . Blogger از حساب‌های Google استفاده می‌کند، بنابراین اگر از قبل یک حساب Google دارید، همه چیز آماده است.

اجرای کد نمونه

یک کلاینت نمونه کار کامل، حاوی تمام کدهای نمونه نشان داده شده در این سند، در پروژه کتابخانه کلاینت دات نت موجود است. نمونه در /trunk/clients/cs/samples/blogger/ConsoleSample.cs در برگه Source مخزن SVN قرار دارد.

قبل از کامپایل و اجرای این نمونه، مقادیر username ، password ، blogName و postId را با مقادیر مناسب به روز کنید. مقادیر username و password نشان دهنده اعتبار مورد استفاده برای ورود به بلاگر است. مقدار blogName شروع URL وبلاگ شماست.

مشتری نمونه چندین عملیات را در وبلاگ ارائه شده برای نشان دادن استفاده از Blogger Data API انجام می دهد.

برای کامپایل نمونه های موجود در این سند در کد خود، using دستورات زیر نیاز دارید:

using Google.GData.Client;
using System.Net;
using System.Xml;
using System.Text.RegularExpressions;

احراز هویت در سرویس بلاگر

با استفاده از Blogger Data API می توانید به فیدهای عمومی و خصوصی دسترسی داشته باشید. فیدهای عمومی نیازی به احراز هویت ندارند، اما فقط خواندنی هستند. اگر می‌خواهید وبلاگ‌ها را اصلاح کنید، مشتری شما باید قبل از درخواست فیدهای خصوصی، احراز هویت کند. این می تواند با استفاده از یکی از دو روش احراز هویت کند: احراز هویت پروکسی AuthSub یا احراز هویت نام کاربری/گذرواژه ClientLogin .

برای اطلاعات بیشتر در مورد احراز هویت با APIهای Google Data به طور کلی، به مستندات احراز هویت مراجعه کنید.

احراز هویت پروکسی AuthSub

احراز هویت پراکسی AuthSub توسط برنامه‌های کاربردی وب استفاده می‌شود که باید کاربران خود را در حساب‌های Google احراز هویت کنند. اپراتور وب سایت و کد مشتری به نام کاربری و رمز عبور کاربر بلاگر دسترسی ندارند. در عوض، کلاینت توکن های AuthSub ویژه ای را دریافت می کند که به مشتری اجازه می دهد از طرف یک کاربر خاص عمل کند. برای اطلاعات بیشتر، به مستندات AuthSub مراجعه کنید.

وقتی کاربر برای اولین بار از برنامه شما بازدید می کند، هنوز احراز هویت نشده است. در این مورد، شما باید برخی از اطلاعات و لینکی را نمایش دهید که کاربر را به صفحه Google هدایت می کند تا درخواست شما برای دسترسی به وبلاگ خود را تأیید کند.

فرض کنید لینک ASP زیر در صفحه شما تعریف شده است:

<asp:HyperLink ID="GotoAuthSubLink" runat="server"/>

سپس برای ساخت URL AuthSubRequest برای برنامه خود، یک فراخوانی از کتابخانه کلاینت دات نت به صورت زیر انجام دهید:

GotoAuthSubLink.Text = "Login to your Google Account";
GotoAuthSubLink.NavigateUrl =
  AuthSubUtil.getRequestUrl("http://www.example.com/RetrieveToken",
  "http://www.blogger.com/feeds/",
  false,
  true);

متد getRequestUrl پارامترهای زیر را می گیرد (مرتبط با پارامترهای پرس و جو مورد استفاده توسط AuthSubRequest handler):

بعدی
آدرس صفحه ای که گوگل باید پس از احراز هویت کاربر را به آن هدایت کند.
دامنه
نشان می دهد که برنامه برای دسترسی به فیدهای Blogger درخواست یک رمز می کند. رشته scope مورد استفاده http://www.blogger.com/feeds/ است (البته با URL-encoded).
امن
نشان می دهد که آیا مشتری یک توکن امن درخواست می کند یا خیر.
جلسه
نشان می دهد که آیا رمز برگشتی را می توان با یک توکن چند منظوره (جلسه) مبادله کرد یا خیر.

مثال بالا تماسی را نشان می دهد که توکن ایمن درخواست نمی کند (مقدار secure false است). URL درخواست حاصل ممکن است به شکل زیر باشد:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2FRetrieveToken

کاربر پیوند به سایت Google را دنبال می کند و در حساب Google خود احراز هویت می کند.

پس از احراز هویت کاربر، سیستم AuthSub آنها را به آدرس اینترنتی که در پارامتر پرس و جو next URL AuthSubRequest مشخص کرده اید هدایت می کند. سیستم AuthSub یک نشانه احراز هویت را به عنوان مقدار پارامتر کوئری token به آن URL اضافه می کند. بنابراین، توکن به عنوان یک متغیر در شی Request.QueryString صفحه ASP قابل دسترسی است. کاربر به یک URL هدایت می شود که به شکل زیر است:

http://www.example.com/RetrieveToken?token=yourAuthToken

این مقدار توکن نشان دهنده یک توکن AuthSub یکبار مصرف است. در این مثال، از آنجایی که session = true مشخص شده است، این توکن را می توان با یک نشانه جلسه AuthSub به صورت زیر مبادله کرد:

SessionsessionToken = AuthSubUtil.exchangeForSessionToken(Request.QueryStringtoken, null);

یعنی توکن یک بار مصرف خود را به متد exchangeForSessionToken به همراه null (برای حالت ثبت نشده) یا یک کلید خصوصی (برای حالت ثبت شده) ارسال می‌کنید و رابط AuthSub یک نشانه جلسه را برمی‌گرداند. برای اطلاعات بیشتر درباره برنامه‌های کاربردی ثبت‌شده و کلیدهای خصوصی، به بخش « درخواست‌های امضا » در اسناد AuthSub مراجعه کنید.

سپس برنامه شما می تواند از مقدار نشانه جلسه در تعاملات بعدی با بلاگر استفاده کند. برای اینکه به کتابخانه سرویس گیرنده دات نت بگویید که به صورت خودکار هدر Authorization (شامل نشانه جلسه) را با هر درخواست ارسال کند، موارد زیر را انجام دهید:

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("blogger", "BloggerSampleApp");
authFactory.Token = SessionsessionToken.ToString();
Service service = new Service(authFactory.ApplicationName);
service.RequestFactory = authFactory;

احراز هویت نام کاربری/گذرواژه ClientLogin

اگر کلاینت شما یک کلاینت «نصب شده» مستقل و تک کاربره است (مانند یک برنامه دسکتاپ) از احراز هویت ClientLogin استفاده کنید. اعتبار شیء سرویس خود را به صورت زیر تنظیم کنید:

Service service = new Service("blogger", "exampleCo-exampleApp-1");
service.Credentials = new GDataCredentials("user@example.com", "secretPassword");
GDataGAuthRequestFactory factory = (GDataGAuthRequestFactory) service.RequestFactory;
factory.AccountType = "GOOGLE";

در قطعه بالا، دو پارامتر را به سازنده Service ارسال می کنیم. اولین پارامتر نام سرویسی است که می خواهیم با آن تعامل داشته باشیم. پارامتر دوم نام برنامه ما به شکل companyName - applicationName - versionID است. ما همچنین Service.RequestFactory را طوری تنظیم کردیم که فقط از نوع حساب GOOGLE استفاده کند تا امکان احراز هویت مناسب برای کاربران G Suite فراهم شود.

برای اطلاعات بیشتر درباره احراز هویت ClientLogin، از جمله درخواست‌ها و پاسخ‌های نمونه، به مستندات احراز هویت برای برنامه‌های نصب‌شده مراجعه کنید.

توجه : برای همه درخواست ها در یک جلسه معین از یک نشانه استفاده کنید. برای هر درخواست بلاگر یک نشانه جدید دریافت نکنید.

توجه : همانطور که در مستندات ClientLogin توضیح داده شده است، درخواست احراز هویت ممکن است با شکست مواجه شود و یک چالش CAPTCHA درخواست کند. اگر می‌خواهید Google چالش CAPTCHA را صادر و رسیدگی کند، کاربر را به https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger بفرستید (به جای URL مربوط به CAPTCHA که در اسناد ClientLogin ارائه شده است).

بازیابی لیستی از وبلاگ ها

Blogger Data API خوراکی را ارائه می دهد که وبلاگ ها را برای یک کاربر خاص فهرست می کند. آن خوراک به عنوان "متافید" شناخته می شود.

کد نمونه زیر از یک شیء Service تایید شده برای بازیابی متافید استفاده می کند و سپس عنوان هر وبلاگ را چاپ می کند.

query.Uri = new Uri("http://www.blogger.com/feeds/default/blogs");
AtomFeed feed = null;
try
{
  feed = service.Query(query);
  foreach (AtomEntry entry in feed.Entries)
  {
    Console.WriteLine("Blog Title: " + entry.Title.Text);
  }
}

به URL استفاده شده توسط متد getFeed توجه کنید. این URL پیش فرض متافید است. لیستی از وبلاگ ها را برای کاربر تأیید شده فعلی برمی گرداند. برای دسترسی به فید برای یک کاربر دیگر، می توانید شناسه کاربر را به جای default در URL متافید قرار دهید. شناسه کاربر رشته اعدادی است که در انتهای URL نمایه کاربر قرار دارد.

ایجاد پست ها

Blogger Data API به شما امکان ایجاد و انتشار مطالب جدید وبلاگ و همچنین ایجاد پیش نویس ورودی ها را می دهد.

همه نمونه‌های زیر فرض می‌کنند که یک شیء Service احراز هویت شده دارید.

توجه : تنظیم یک نویسنده سفارشی برای پست ها در حال حاضر پشتیبانی نمی شود. همه پست های جدید به گونه ای ظاهر می شوند که گویی توسط کاربر تأیید شده فعلی ایجاد شده اند.

انتشار پست وبلاگ

می توانید از کتابخانه مشتری دات نت برای انتشار مطالب جدید وبلاگ استفاده کنید.

ابتدا یک شی AtomEntry برای نمایش پست وبلاگ ایجاد کنید. سپس می توانید عنوان، محتوا و سایر ویژگی های پست وبلاگ را تنظیم کنید. در نهایت از شی Service برای درج پست استفاده کنید. در اینجا مثالی از نحوه انتشار یک پست وبلاگ جدید آورده شده است: 

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
  "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
  "<p>He is the last man on earth I would ever desire to marry.</p>" +
  "<p>Whatever shall I do?</p>" +
  "</div>";
newPost.Content.Type = "xhtml";

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

متد Insert URL پست سرویس را به عنوان پارامتر می گیرد. سپس متد ورودی را همانطور که توسط Blogger ذخیره شده است برمی گرداند. ورودی برگشتی همان ورودی است که ارسال کردید، اما حاوی عناصر مختلفی است که توسط Blogger اضافه شده است، مانند شناسه پست.

اگر درخواست شما به دلایلی ناموفق باشد، Blogger ممکن است کد وضعیت دیگری را برگرداند. برای اطلاعات در مورد کدهای وضعیت، به سند مرجع پروتکل Google Data API مراجعه کنید.

ایجاد پیش نویس پست وبلاگ

پست‌های پیش‌نویس مانند پست‌های عمومی ایجاد می‌شوند، اما شما باید ویژگی draft شی AtomEntry را تنظیم کنید. پست وبلاگ بالا می تواند به عنوان پیش نویس با افزودن خط برجسته ایجاد شود: 

AtomEntry newPost = new AtomEntry();
newPost.Title.Text = "Marriage!";
newPost.Content = new AtomContent();
newPost.Content.Content = "<div xmlns='http://www.w3.org/1999/xhtml'>" +
    "<p>Mr. Darcy has <em>proposed marriage</em> to me!</p>" +
    "<p>He is the last man on earth I would ever desire to marry.</p>" +
    "<p>Whatever shall I do?</p>" +
    "</div>";
newPost.Content.Type = "xhtml";
newPost.IsDraft = true;

Uri blogFeedUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
AtomEntry createdEntry = service.Insert(blogFeedUri, newPost);

می‌توانید با بازیابی پست پیش‌نویس، تنظیم ویژگی پیش‌نویس روی false، و سپس به‌روزرسانی پست، یک پست وبلاگ پیش‌نویس موجود را به یک پست منتشر شده تبدیل کنید. ما بازیابی و به روز رسانی پست ها را در دو بخش بعدی پوشش خواهیم داد.

در حال بازیابی پست ها

بخش‌های زیر نحوه بازیابی فهرستی از پست‌های وبلاگ، با و بدون پارامترهای پرس و جو را شرح می‌دهند.

می‌توانید بدون احراز هویت، فید عمومی Blogger را درخواست کنید. بنابراین، قبل از بازیابی پست‌ها از یک وبلاگ عمومی، نیازی به تنظیم اعتبار یا احراز هویت AuthSub ندارید.

بازیابی همه پست های وبلاگ

برای بازیابی پست های کاربر، همان روش getFeed مورد استفاده برای بازیابی متافید وبلاگ ها را فراخوانی کنید، اما این بار URL فید وبلاگ-پست را ارسال کنید: 

query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
feed = service.Query(query);
Console.WriteLine(feed.Title.Text);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("Entry Title: " + entry.Title.Text);
}

بازیابی پست ها با استفاده از پارامترهای پرس و جو

Blogger Data API به شما امکان می‌دهد مجموعه‌ای از ورودی‌ها را درخواست کنید که با معیارهای مشخص شده مطابقت دارند، مانند درخواست پست‌های وبلاگ منتشر شده یا به‌روزرسانی شده در یک محدوده تاریخ معین. برای انجام این کار، یک شی FeedQuery ایجاد می کنید و آن را به متد Service.Query() ارسال می کنید.

به عنوان مثال، برای ارسال یک جستجوی محدوده تاریخ، اعضای MinPublication و MaxPublication شی FeedQuery را تنظیم کنید. قطعه کد زیر عنوان هر پست وبلاگ منتشر شده را بین زمان شروع و پایان مشخص شده چاپ می کند: 

FeedQuery query = new FeedQuery();
query.Uri = new Uri("http://www.blogger.com/feeds/" + blogId + "/posts/default");
query.MinPublication = new DateTime(2006, 1, 1);
query.MaxPublication = new DateTime(2007, 4, 12);
AtomFeed feed = service.Query(query);
foreach (AtomEntry entry in feed.Entries)
{
  Console.WriteLine("  Entry Title: " + entry.Title.Text);
}

توجه داشته باشید که شی FeedQuery با استفاده از همان URL فید پست استفاده شده برای بازیابی پست ها ساخته شده است.

Blogger Data API از پارامترهای جستجوی زیر پشتیبانی می کند:

alt
نوع فید برای بازگشت، مانند atom (پیش‌فرض) یا rss .
/category
برای فیلتر کردن نتایج فید، دسته‌ها (همچنین به عنوان برچسب شناخته می‌شوند) را مشخص کنید. برای مثال، http://www.blogger.com/feeds/ blogID /posts/default/-/Fritz/Laurie ورودی‌هایی را با هر دو برچسب Fritz و Laurie برمی‌گرداند.
حداکثر نتایج
حداکثر تعداد ورودی برای بازگشت.
با سفارش
ترتیبی که برای بازگرداندن ورودی‌ها، مانند lastmodified (پیش‌فرض)، starttime ، یا updated .
منتشر شده-دقیقه، منتشر شده-حداکثر
محدوده تاریخ انتشار ورودی.
شروع-شاخص
ایندکس بر اساس 1 اولین نتیجه ای که بازیابی می شود (برای صفحه بندی).
به روز شده-min، به روز-حداکثر
محدودیت در تاریخ های به روز رسانی ورودی. این پارامترهای پرس و جو نادیده گرفته می شوند مگر اینکه پارامتر orderby روی updated تنظیم شود.

برای اطلاعات بیشتر در مورد پارامترهای پرس و جو، به راهنمای مرجع API داده Blogger و راهنمای مرجع Google Data APIs مراجعه کنید.

به روز رسانی پست ها

برای به‌روزرسانی یک پست وبلاگ موجود، ابتدا ورودی مورد نظر برای به‌روزرسانی را بازیابی می‌کنید، سپس آن را تغییر می‌دهید و سپس با استفاده از روش Update() ورودی آن را برای Blogger ارسال می‌کنید. قطعه کد زیر عنوان یک ورودی وبلاگ را تغییر می دهد، با این فرض که شما قبلاً ورودی را از سرور بازیابی کرده اید. 

static AtomEntry EditEntry(AtomEntry toEdit)
{
  // Edit the entry by changing the Title and calling Update().
  if (toEdit != null)
  {
    toEdit.Title.Text = "Marriage Woes!";
    toEdit = toEdit.Update();
  }
  return toEdit;
}

کد بالا یک AtomEntry را برمی گرداند که حاوی کل پست به روز شده جدید است. برای به روز رسانی هر ویژگی دیگر، کافی است قبل از فراخوانی Update() آنها را در شی AtomEntry تنظیم کنید.

توجه : تغییر داده های نویسنده مرتبط با پست ها در حال حاضر پشتیبانی نمی شود.

حذف پست ها

برای حذف یک پست، متد Delete را در یک شیء موجود AtomEntry فراخوانی کنید، مانند این: 

static void DeleteEntry(AtomEntry toDelete)
{
  // Delete the edited entry
  if (toDelete != null)
  {
    toDelete.Delete();
  }
}

نظرات

Blogger Data API امکان ایجاد، بازیابی و حذف نظرات را فراهم می کند. به روز رسانی نظرات پشتیبانی نمی شود (و نه در رابط وب موجود است).

ایجاد نظرات

برای ارسال نظر، یک شی AtomEntry ایجاد کنید و آن را به صورت زیر درج کنید: 

AtomEntry comment;
comment = new AtomEntry();
comment.Title.Text = "This is my first comment";
comment.Content.Content = "This is my first comment";
Uri commentPostUri = new Uri("http://www.blogger.com/feeds/" + blogId + "/" + entryId + "/comments/default");
postedComment = service.Insert(commentPostUri, comment);

توجه : در حال حاضر، فقط می‌توانید برای وبلاگی که متعلق به کاربر تأیید شده است، نظر ارسال کنید.

توجه : تنظیم یک نویسنده سفارشی برای نظرات در حال حاضر پشتیبانی نمی شود. همه نظرات جدید به گونه ای ظاهر می شوند که گویی توسط کاربر تأیید شده فعلی ایجاد شده اند.

بازیابی نظرات

می‌توانید نظرات یک پست خاص را از URL خوراک نظرات آن پست بازیابی کنید: 

static void ListEntryComments(Service service, Uri commentUri)
{
  if (commentUri != null)
  {
    // Retrieve all comments on a blog entry
    FeedQuery query = new FeedQuery();
    query.Uri = commentUri;
    AtomFeed feed = service.Query(query);
    foreach (AtomEntry entry in feed.Entries)
    {
      Console.WriteLine("  Comment Title: " + entry.Title.Text);
    }
  }
}

یا می توانید نظرات همه پست ها را با استفاده از URL خوراک نظرات وبلاگ دریافت کنید: 

http://www.blogger.com/feeds/blogID/comments/default

حذف نظرات

برای حذف یک نظر، متد Delete() را بر روی یک شیء کامنت موجود AtomEntry مانند این فراخوانی کنید: 

static void DeleteComment(AtomEntry commentEntry)
{
  if (commentEntry != null)
  {
    // Delete the comment.
    commentEntry.Delete();
  }
}

بازگشت به بالا