مبانی پروتکل Google Data APIs

این سند اصول اولیه پروتکل مورد استفاده توسط Google Data API را شرح می دهد، از جمله نمونه هایی از ظاهر یک پرس و جو، ظاهر نتایج و غیره.

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

حضار

این سند برای هر کسی در نظر گرفته شده است که می‌خواهد ایده کلی قالب و پروتکل XML مورد استفاده توسط Google Data API را درک کند.

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

این سند فرض می‌کند که شما اصول XML، فضاهای نام، فیدهای مشترک، و درخواست‌های GET ، POST ، PUT ، و DELETE در HTTP و همچنین مفهوم «منبع» HTTP را می‌دانید. برای اطلاعات بیشتر در مورد این موارد، به بخش منابع اضافی این سند مراجعه کنید.

این سند به هیچ زبان برنامه نویسی خاصی متکی نیست. کلاینت شما می تواند با استفاده از هر زبان برنامه نویسی که به شما امکان می دهد درخواست های HTTP را صادر کنید و پاسخ های مبتنی بر XML را تجزیه و تحلیل کنید، با سرور تعامل داشته باشد.

مثال ها

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

درخواست فید یا منبع دیگر

فرض کنید یک فید به نام /myFeed وجود دارد، و فرض کنید که در حال حاضر هیچ ورودی وجود ندارد. برای مشاهده آن، درخواست زیر را به سرور ارسال کنید:

GET /myFeed

سرور پاسخ می دهد:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
</feed>

توجه داشته باشید که اگرچه فید حاوی هیچ ورودی نیست، اما حاوی فراداده است، مانند عنوان و نام نویسنده.

درج ورودی جدید

برای ایجاد یک ورودی جدید، یک درخواست POST ارسال کنید و نمایش XML ورودی جدید را ارائه دهید:

POST /myFeed

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my entry</content>
</entry>

توجه داشته باشید که عناصر استاندارد Atom <id> , <link> یا <updated> را ارائه نمی کنید. سرور آن ها را در پاسخ به درخواست POST شما ایجاد می کند. همچنین توجه داشته باشید که نویسنده یک فید نباید همان شخص نویسنده یک ورودی باشد.

سرور پاسخ می دهد:

201 CREATED

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/1/"/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my entry</content>
</entry>

جستجوی رشته

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

GET /myFeed?q=This

سرور با تمام ورودی هایی که با رشته جستجو This مطابقت دارند پاسخ می دهد. (در این مورد فقط یک مورد وجود دارد.)

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
  <entry>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/1/"/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
    <title type="text">Entry 1</title>
    <content type="text">This is my entry</content>
  </entry>
</feed>

به روز رسانی یک ورودی

برای به‌روزرسانی ورودی موجود، از PUT با URI ویرایش ورودی (همانطور که سرور در مثال قبلی در عنصر <link rel="edit"> ارائه کرده است) استفاده کنید.

اگر فایروال شما اجازه PUT نمی دهد، یک HTTP POST انجام دهید و هدر override متد را به صورت زیر تنظیم کنید:

X-HTTP-Method-Override: PUT

در مثال زیر، متن ورودی را از مقدار قدیمی آن ("This is my entry") به مقدار جدید ("This is my first entry") تغییر می دهیم.

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/1/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my first entry.</content>
</entry>

سرور پاسخ می دهد:

200 OK

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my first entry.</content>
</entry>

توجه داشته باشید که URI ویرایش تغییر کرده است. اکنون به جای "/1/" با "/2/" به پایان می رسد. شماره نهایی در ویرایش URI یک شماره نسخه است. برای اطلاعات بیشتر در مورد نسخه ها، به بخش همزمانی خوش بینانه سند مرجع پروتکل مراجعه کنید.

برای مشاهده ورودی جدید در متن، دوباره کل منبع را درخواست کنید:

GET /myFeed

سرور پاسخ می دهد:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
  <entry>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
    <title type="text">Entry 1</title>
    <content type="text">This is my first entry.</content>
  </entry>
</feed>

حذف یک ورودی

برای حذف یک ورودی موجود، با استفاده از URI ویرایش ورودی (همانطور که سرور در مثال قبلی ارائه کرده است) یک درخواست DELETE ارسال کنید.

اگر فایروال شما اجازه DELETE را نمی دهد، یک HTTP POST انجام دهید و هدر override متد را به صورت زیر تنظیم کنید:

 X-HTTP-Method-Override: DELETE

مثال زیر یک ورودی را حذف می کند:

DELETE /myFeed/1/2/

سرور پاسخ می دهد:

200 OK

یک GET دیگر انجام دهید تا ببینید که فید اکنون حاوی هیچ ورودی نیست:

GET /myFeed

سرور پاسخ می دهد:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
</feed>

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

منابع اضافی

ممکن است اسناد شخص ثالث زیر برای شما مفید باشد:

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