Blogger JSON API: استفاده از API

این سند نحوه استفاده از ویژگی‌های مشترک Blogger JSON API را با استفاده از سبک تماس RESTful شرح می‌دهد.

فهرست

مقدمه

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

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

تأیید درخواست ها و شناسایی درخواست شما

هر درخواستی که برنامه شما به Blogger JSON API ارسال می کند باید برنامه شما را به Google شناسایی کند. دو راه برای شناسایی برنامه شما وجود دارد: استفاده از یک توکن OAuth 2.0 (که درخواست را نیز مجاز می کند) و/یا استفاده از کلید API برنامه . در اینجا نحوه تعیین اینکه کدام یک از این گزینه ها استفاده شود آورده شده است:

  • اگر درخواست نیاز به مجوز داشته باشد (مانند درخواست برای داده های خصوصی یک فرد)، برنامه باید یک توکن OAuth 2.0 را همراه با درخواست ارائه کند. برنامه ممکن است کلید API را نیز ارائه کند، اما لازم نیست.
  • اگر درخواست به مجوز نیاز ندارد (مانند درخواست برای داده‌های عمومی)، برنامه باید یا کلید API یا یک نشانه OAuth 2.0 یا هر دو را ارائه دهد - هر گزینه ای که برای شما راحت تر است.

درباره پروتکل های مجوز

برنامه شما باید از OAuth 2.0 برای تأیید درخواست ها استفاده کند. هیچ پروتکل مجوز دیگری پشتیبانی نمی شود.

توجه : Blogger JSON API در حال حاضر از ورود به سیستم همزمان با درخواست دسترسی به داده ( ترکیبی ) یا تفویض اختیار در سطح دامنه ( 2LO ) پشتیبانی نمی‌کند.

تأیید درخواست ها با OAuth 2.0

درخواست‌ها به Blogger JSON API برای داده‌های کاربر غیرعمومی باید توسط یک کاربر احراز هویت مجاز باشد.

جزئیات فرآیند مجوز یا "جریان" برای OAuth 2.0 بسته به نوع برنامه ای که می نویسید تا حدودی متفاوت است. فرآیند کلی زیر برای همه انواع برنامه ها اعمال می شود:

  1. هنگامی که برنامه خود را ایجاد می کنید، آن را در Google ثبت می کنید . سپس Google اطلاعاتی را که بعداً به آن نیاز خواهید داشت، مانند شناسه مشتری و راز مشتری ارائه می دهد.
  2. Blogger JSON API را در بخش خدمات کنسول Google APIs فعال کنید. (اگر در کنسول لیست نشده است، از این مرحله رد شوید.)
  3. هنگامی که برنامه شما نیاز به دسترسی به داده های کاربر دارد، از Google دامنه دسترسی خاصی را می خواهد.
  4. Google یک گفتگوی OAuth را به کاربر نمایش می‌دهد و از او می‌خواهد برنامه شما را مجاز کند تا برخی از داده‌های خود را درخواست کند.
  5. اگر کاربر تأیید کند، گوگل به برنامه شما یک رمز دسترسی کوتاه مدت می دهد.
  6. برنامه شما با پیوست کردن رمز دسترسی به درخواست، داده های کاربر را درخواست می کند.
  7. اگر Google تشخیص دهد که درخواست شما و رمز معتبر هستند، داده‌های درخواستی را برمی‌گرداند.

برخی از جریان‌ها شامل مراحل اضافی هستند، مانند استفاده از نشانه‌های تازه‌سازی برای به دست آوردن نشانه‌های دسترسی جدید. برای اطلاعات دقیق درباره جریان‌ها برای انواع مختلف برنامه‌ها، به اسناد OAuth 2.0 Google مراجعه کنید.

در اینجا اطلاعات محدوده OAuth 2.0 برای Blogger JSON API آمده است:

https://www.googleapis.com/auth/blogger

برای درخواست دسترسی با استفاده از OAuth 2.0، برنامه شما به اطلاعات محدوده و همچنین اطلاعاتی که Google در حین ثبت برنامه ارائه می کند (مانند شناسه مشتری و/یا رمز سرویس گیرنده) نیاز دارد.

نکته: کتابخانه های سرویس گیرنده Google APIs می توانند برخی از فرآیندهای مجوز را برای شما انجام دهند. آنها برای انواع زبان های برنامه نویسی در دسترس هستند. برای جزئیات بیشتر صفحه کتابخانه ها و نمونه ها را بررسی کنید.

به دست آوردن و استفاده از یک کلید API

درخواست‌های Blogger JSON API برای داده‌های عمومی باید همراه با یک شناسه باشد که می‌تواند یک کلید API یا یک نشانه تأیید باشد.

برای به دست آوردن یک کلید API، از کنسول APIs دیدن کنید. در بخش خدمات، [api_name] را فعال کنید. اگر شرایط خدمات ظاهر شد، آنها را بخوانید و بپذیرید.

بعد، به صفحه دسترسی API بروید. کلید API نزدیک به پایین آن صفحه، در قسمتی با عنوان «دسترسی ساده API» قرار دارد.

بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey را به همه URL های درخواستی اضافه کند.

کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.

کار با وبلاگ ها

بازیابی یک وبلاگ

می توانید با ارسال یک درخواست HTTP GET به URI وبلاگ، اطلاعات یک منبع بلاگ خاص را بازیابی کنید. URI برای یک منبع وبلاگ دارای فرمت زیر است:

https://www.googleapis.com/blogger/v2/blogs/blogId

درخواست

به عنوان مثال:

GET https://www.googleapis.com/blogger/v2/blogs/2399953&key=YOUR-API-KEY

از آنجایی که یک کاربر برای بازیابی یک وبلاگ عمومی نیازی به احراز هویت نیست، شما مجبور نیستید هدر HTTP Authorization را با این درخواست GET ارائه دهید. اما اگر آن هدر را ارائه نکردید، باید یک کلید API ارائه دهید.

بلاگر همچنین دارای وبلاگ های خصوصی است که نیاز به احراز هویت دارند.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با کد وضعیت HTTP 200 OK و داده های وبلاگ پاسخ می دهد:

200 OK

{
  "kind": "blogger#blog",
  "id": "2399953",
  "name": "Blogger Buzz",
  "description": "The Official Buzz from Blogger at Google",
  "published": "2007-04-23T22:17:29.261Z",
  "updated": "2011-08-02T06:01:15.941Z",
  "url": "http://buzz.blogger.com/",
  "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953",
  "posts": {
    "totalItems": 494,
    "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts"
  },
  "pages": {
    "totalItems": 2,
    "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/pages"
  },
  "locale": {
    "language": "en",
    "country": "",
    "variant": ""
  }
}

بازیابی وبلاگ های یک کاربر

می‌توانید با ارسال یک درخواست HTTP GET به URI مجموعه وبلاگ‌ها، فهرستی از وبلاگ‌های کاربر را بازیابی کنید:

https://www.googleapis.com/blogger/v2/users/userId/blogs

درخواست

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

GET https://www.googleapis.com/blogger/v2/users/self/blogs
Authorization: /* OAuth 2.0 token here */

توجه : کاربر باید برای فهرست کردن وبلاگ های خود احراز هویت شود، بنابراین باید سرصفحه HTTP Authorization را با درخواست GET ارائه دهید.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و نمایش کامل لیست وبلاگ های کاربر پاسخ می دهد:

200 OK

{
  "kind": "blogger#blogList",
  "items": [
    {
      "kind": "blogger#blog",
      "id": "4967929378133675647",
      "name": "Brett's Test Blawg",
      "description": "",
      "published": "2010-10-06T23:33:31.662Z",
      "updated": "2011-08-08T06:50:02.005Z",
      "url": "http://brettmorgan-test-blawg.blogspot.com/",
      "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647",
      "posts": {
        "totalItems": 13,
        "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/posts"
      },
      "pages": {
        "totalItems": 1,
        "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages"
      },
      "locale": {
        "language": "en",
        "country": "",
        "variant": ""
      }
    }
  ]
}

کار با پست ها

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

می‌توانید با ارسال درخواست GET به URI مجموعه پست‌ها، فهرستی از پست‌ها را از یک وبلاگ خاص بازیابی کنید. URI برای مجموعه پست ها فرمت زیر را دارد:

https://www.googleapis.com/blogger/v2/blogs/blogId/posts

درخواست

به عنوان مثال:

GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts&key=YOUR-API-KEY

از آنجایی که یک کاربر برای بازیابی پست ها از یک وبلاگ عمومی نیازی به احراز هویت نیست، شما مجبور نیستید هدر HTTP Authorization را با این درخواست GET ارائه دهید. اما اگر آن هدر را ارائه نکردید، باید یک کلید API ارائه دهید.

بلاگر همچنین دارای وبلاگ های خصوصی است که نیاز به احراز هویت دارند.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و لیست پست ها پاسخ می دهد:

200 OK

{
  "kind": "blogger#postList",
  "nextPageToken": "CgkIChiAkceVjiYQ0b2SAQ",
  "prevPageToken": "CgkIChDBwrK3mCYQ0b2SAQ",
  "items": [
    {
      "kind": "blogger#post",
      "id": "7706273476706534553",
      "blog": {
        "id": "2399953"
      },
      "published": "2011-08-01T19:58:00.000Z",
      "updated": "2011-08-01T19:58:51.947Z",
      "url": "http://buzz.blogger.com/2011/08/latest-updates-august-1st.html",
      "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553",
      "title": "Latest updates, August 1st",
      "content": "elided for readability",
      "author": {
        "id": "401465483996",
        "displayName": "Brett Wiltshire",
        "url": "http://www.blogger.com/profile/01430672582309320414",
        "image": {
          "url": "http://4.bp.blogspot.com/_YA50adQ-7vQ/S1gfR_6ufpI/AAAAAAAAAAk/1ErJGgRWZDg/S45/brett.png"
         }
      },
      "replies": {
        "totalItems": "0",
        "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553/comments"
      }
    },
    {
      "kind": "blogger#post",
      "id": "6069922188027612413",
      elided for readability
    }
  ]
}

بازیابی یک پست خاص

می توانید با ارسال درخواست GET به URI منبع پست، یک پست خاص را از یک وبلاگ بازیابی کنید. URI برای یک منبع پست دارای فرمت زیر است:

https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId

درخواست

به عنوان مثال:

GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553&key=YOUR-API-KEY

از آنجایی که یک کاربر برای بازیابی پست ها از یک وبلاگ عمومی نیازی به احراز هویت نیست، شما مجبور نیستید هدر HTTP Authorization را با این درخواست GET ارائه دهید. اما اگر آن هدر را ارائه نکردید، باید یک کلید API ارائه دهید.

بلاگر همچنین دارای وبلاگ های خصوصی است که نیاز به احراز هویت دارند.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و محتوای پست پاسخ می دهد:

200 OK

{
  "kind": "blogger#post",
  "id": "7706273476706534553",
  "blog": {
    "id": "2399953"
  },
  "published": "2011-08-01T19:58:00.000Z",
  "updated": "2011-08-01T19:58:51.947Z",
  "url": "http://buzz.blogger.com/2011/08/latest-updates-august-1st.html",
  "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553",
  "title": "Latest updates, August 1st",
  "content": "elided for readability",
  "author": {
    "id": "401465483996",
    "displayName": "Brett Wiltshire",
    "url": "http://www.blogger.com/profile/01430672582309320414",
    "image": {
      "url": "http://4.bp.blogspot.com/_YA50adQ-7vQ/S1gfR_6ufpI/AAAAAAAAAAk/1ErJGgRWZDg/S45/brett.png"
    }
  },
  "replies": {
    "totalItems": "0",
    "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/7706273476706534553/comments"
  }
}

کار با نظرات

بازیابی نظرات برای یک پست

می توانید با ارسال یک درخواست GET به URI مجموعه نظرات، فهرستی از نظرات یک پست را بازیابی کنید. URI برای مجموعه نظرات دارای فرمت زیر است:

https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments

درخواست

به عنوان مثال:

GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments&key=YOUR-API-KEY

از آنجایی که یک کاربر برای بازیابی نظرات از یک وبلاگ عمومی نیازی به احراز هویت نیست، لازم نیست سرصفحه HTTP Authorization را با این درخواست GET ارائه دهید. اما اگر آن هدر را ارائه نکردید، باید یک کلید API ارائه دهید.

بلاگر همچنین دارای وبلاگ های خصوصی است که نیاز به احراز هویت دارند.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و لیست نظرات پاسخ می دهد:

200 OK

{
  "kind": "blogger#commentList",
  "nextPageToken": "CgkIFBDwjvDXlyYQ0b2SARj9mZe9n8KsnlQ",
  "prevPageToken": "CgkIFBisvMGRlyYQ0b2SARj9mZe9n8KsnlQ",
  "items": [
    {
       "kind": "blogger#comment",
       "id": "9200761938824362519",
       "post": {
         "id": "6069922188027612413"
       },
       "blog": {
         "id": "2399953"
       },
       "published": "2011-07-28T19:19:57.740Z",
       "updated": "2011-07-28T21:29:42.015Z",
       "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519",
       "content": "elided",
       "author": {
         "id": "530579030283",
         "displayName": "elided",
         "url": "elided",
         "image": {
           "url": "elided"
         }
       }
    },
    {
      "kind": "blogger#comment",
      "id": "400101178920857170",
      elided for readability
    }
  ]
}

بازیابی یک نظر خاص

می توانید با ارسال یک درخواست GET به Comments Resource URI یک نظر خاص را از یک پست بازیابی کنید. URI برای منبع نظرات فرمت زیر را دارد:

https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments/commentId

درخواست

به عنوان مثال:

GET https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519&key=YOUR-API-KEY

از آنجایی که یک کاربر برای بازیابی نظرات از یک وبلاگ عمومی نیازی به احراز هویت نیست، لازم نیست سرصفحه HTTP Authorization را با این درخواست GET ارائه دهید. اما اگر آن هدر را ارائه نکردید، باید یک کلید API ارائه دهید.

بلاگر همچنین دارای وبلاگ های خصوصی است که نیاز به احراز هویت دارند.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و داده های نظر پاسخ می دهد:

200 OK

{
  "kind": "blogger#comment",
  "id": "9200761938824362519",
  "post": {
    "id": "6069922188027612413"
  },
  "blog": {
    "id": "2399953"
  },
  "published": "2011-07-28T19:19:57.740Z",
  "updated": "2011-07-28T21:29:42.015Z",
  "selfLink": "https://www.googleapis.com/blogger/v2/blogs/2399953/posts/6069922188027612413/comments/9200761938824362519",
  "content": "elided",
  "author": {
    "id": "530579030283",
    "displayName": "elided",
    "url": "elided",
    "image": {
      "url": "elided"
    }
  }
}

کار با صفحات

بازیابی صفحات برای وبلاگ

می توانید با ارسال درخواست GET به URI مجموعه صفحات، فهرستی از صفحات را برای وبلاگ بازیابی کنید. URI برای مجموعه صفحات دارای فرمت زیر است:

https://www.googleapis.com/blogger/v2/blogs/blogId/pages

درخواست

به عنوان مثال:

GET https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages&key=YOUR-API-KEY

از آنجایی که یک کاربر برای بازیابی صفحات از یک وبلاگ عمومی نیازی به احراز هویت نیست، لازم نیست سرصفحه HTTP Authorization را با این درخواست GET ارائه دهید. اما اگر آن هدر را ارائه نکردید، باید یک کلید API ارائه دهید.

بلاگر همچنین دارای وبلاگ های خصوصی است که نیاز به احراز هویت دارند.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و لیست صفحات پاسخ می دهد:

200 OK

{
  "kind": "blogger#pageList",
  "items": [
    {
      "kind": "blogger#page",
      "id": "273541696466681878",
      "blog": {
        "id": "4967929378133675647"
      },
      "published": "2011-07-14T16:16:00.000Z",
      "updated": "2011-07-14T16:16:23.602Z",
      "url": "http://brettmorgan-test-blawg.blogspot.com/p/static-content.html",
      "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages/273541696466681878",
      "title": "Static Content",
      "content": "elided for readability",
      "author": {
        "id": "901569848744",
        "displayName": "brett",
        "url": "http://www.blogger.com/profile/16258312240222542576",
        "image": {
          "url": "https://resources.blogblog.com/img/b16-rounded.gif"
        }
      }
    }
  ]
}

بازیابی یک صفحه خاص

با ارسال درخواست GET به URI منابع صفحات می توانید یک صفحه خاص را از وبلاگ بازیابی کنید. URI برای یک منبع صفحات دارای فرمت زیر است:

https://www.googleapis.com/blogger/v2/blogs/blogId/pages/pageId

درخواست

به عنوان مثال:

GET https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages/273541696466681878&key=YOUR-API-KEY

از آنجایی که یک کاربر برای بازیابی صفحات از یک وبلاگ عمومی نیازی به احراز هویت نیست، لازم نیست سرصفحه HTTP Authorization را با این درخواست GET ارائه دهید. اما اگر آن هدر را ارائه نکردید، باید یک کلید API ارائه دهید.

بلاگر همچنین دارای وبلاگ های خصوصی است که نیاز به احراز هویت دارند.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و داده های صفحه پاسخ می دهد:

200 OK

{
  "kind": "blogger#page",
  "id": "273541696466681878",
  "blog": {
    "id": "4967929378133675647"
  },
  "published": "2011-07-14T16:16:00.000Z",
  "updated": "2011-07-14T16:16:23.602Z",
  "url": "http://brettmorgan-test-blawg.blogspot.com/p/static-content.html",
  "selfLink": "https://www.googleapis.com/blogger/v2/blogs/4967929378133675647/pages/273541696466681878",
  "title": "Static Content",
  "content": "elided for readability",
  "author": {
    "id": "901569848744",
    "displayName": "brett",
    "url": "http://www.blogger.com/profile/16258312240222542576",
    "image": {
      "url": "https://resources.blogblog.com/img/b16-rounded.gif"
    }
  }
}

کار با کاربران

بازیابی یک کاربر

شما می توانید اطلاعات یک کاربر را با ارسال یک درخواست HTTP GET به Users Resource URI بازیابی کنید:

https://www.googleapis.com/blogger/v2/users/userId

درخواست

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

GET https://www.googleapis.com/blogger/v2/users/self
Authorization: /* OAuth 2.0 token here */

توجه : کاربر باید برای فهرست کردن اطلاعات خود احراز هویت شود، بنابراین باید سرصفحه HTTP Authorization را با درخواست GET ارائه دهید.

واکنش

اگر درخواست با موفقیت انجام شود، سرور با یک کد وضعیت HTTP 200 OK و پیوندی به لیست وبلاگ های کاربر پاسخ می دهد:

200 OK

{
  "kind": "blogger#user",
  "id": "901569848744",
  "selfLink": "https://www.googleapis.com/blogger/v2/users/901569848744",
  "blogs": {
    "selfLink": "https://www.googleapis.com/blogger/v2/users/901569848744/blogs"
  }
}

پارامترهای پرس و جو استاندارد

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

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