اخطار : این صفحه درباره APIهای قدیمی Google، Google Data APIها است. فقط مربوط به APIهایی است که در فهرست راهنمای Google Data APIs فهرست شده اند، که بسیاری از آنها با APIهای جدیدتر جایگزین شده اند. برای اطلاعات در مورد یک API جدید خاص، به مستندات API جدید مراجعه کنید. برای اطلاعات در مورد تأیید درخواست‌ها با یک API جدیدتر، به تأیید اعتبار و مجوز حساب‌های Google مراجعه کنید.
این سند اصول اولیه پروتکل داده Google را که توسط بسیاری از APIهای Google استفاده می‌شود، از جمله نمونه‌هایی از ظاهر یک پرس و جو، ظاهر نتایج و غیره توصیف می‌کند.
برای اطلاعات بیشتر در مورد پروتکل داده Google، به صفحه نمای کلی راهنمای برنامه‌نویس و مرجع پروتکل مراجعه کنید.
حضار
این سند برای هر کسی در نظر گرفته شده است که می‌خواهد ایده کلی قالب و پروتکل XML مورد استفاده توسط Google Data API را درک کند.
حتی اگر فقط می‌خواهید کدی بنویسید که از کتابخانه‌های مشتری خاص زبان استفاده می‌کند، ممکن است بخواهید این سند را بخوانید تا بفهمید در زیر لایه انتزاعی کلاینت-کتابخانه چه می‌گذرد.
این سند فرض می‌کند که شما اصول XML، فضاهای نام، فیدهای اشتراکی، و درخواست‌های GET ، POST ، PUT ، و DELETE در HTTP و همچنین مفهوم HTTP از یک "منبع" را درک می‌کنید. برای اطلاعات بیشتر در مورد این موارد، به بخش منابع اضافی این سند مراجعه کنید.
این سند به هیچ زبان برنامه نویسی خاصی متکی نیست. کلاینت شما می تواند با استفاده از هر زبان برنامه نویسی که به شما امکان می دهد درخواست های HTTP را صادر کنید و پاسخ های مبتنی بر XML را تجزیه و تحلیل کنید، با سرور تعامل داشته باشد.
اگر می‌خواهید نمونه‌های موجود در این سند را بدون نوشتن هیچ کدی امتحان کنید، ممکن است ابزارهای خط فرمان cURL یا Wget مفید باشند. برای اطلاعات بیشتر، به صفحات کتابچه راهنمای آن ابزارها یا سند استفاده از cURL برای تعامل با سرویس هایی که از پروتکل داده های Google استفاده می کنند، مراجعه کنید.
مثال ها
مثال‌های زیر درخواست‌های HTTP را که ممکن است با استفاده از پروتکل Google Data Protocol API مستقیماً به یک سرویس عمومی ارسال کنید و نتایجی را که ممکن است دریافت کنید نشان می‌دهد. برای مثال‌هایی از نحوه ارسال درخواست‌ها با استفاده از زبان‌های برنامه‌نویسی مختلف، به نمونه‌های خاص زبان و کتابخانه‌های مشتری مراجعه کنید. برای کسب اطلاعات در مورد استفاده از پروتکل داده Google با خدمات خاص Google، به مستندات خاص سرویس مراجعه کنید.
درخواست فید یا منبع دیگر
فرض کنید یک فید به نام /myFeed وجود دارد، و فرض کنید که در حال حاضر هیچ ورودی وجود ندارد. برای مشاهده آن، درخواست HTTP زیر را به سرور ارسال کنید:
GET /myFeed
سرور پاسخ می دهد:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
<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>
توجه داشته باشید که اگرچه فید حاوی هیچ ورودی نیست، اما حاوی فراداده است، مانند عنوان و نام نویسنده. همچنین حاوی یک شناسه نسخه، به شکل HTTP ETag است.
درج ورودی جدید
برای ایجاد یک ورودی جدید، یک درخواست POST ارسال کنید و نمایش XML ورودی جدید را ارائه دهید:
POST /myFeed
<?xml version='1.0' encoding='utf-8'?>
<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' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
<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' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
<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 gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/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 ویرایش ورودی ارسال کنید. ویرایش URI در مثال قبلی به عنوان ویژگیhrefعنصر<link rel='edit'>ظاهر می‌شود.
همچنین باید ETag ورودی اصلی را مشخص کنید تا اطمینان حاصل شود که تغییرات دیگران را بازنویسی نمی‌کنید.
در مثال زیر، متن ورودی را از مقدار قدیمی آن ("This is my entry") به مقدار جدید ("This is my first entry") تغییر می دهیم.
PUT /myFeed/1/1/
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/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' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/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>
توجه داشته باشید که ETag تغییر کرده است. برای اطلاعات بیشتر در مورد نسخه‌های منابع، به بخش نسخه‌سازی منابع (ETags) در سند مرجع پروتکل مراجعه کنید.
برای مشاهده ورودی جدید در متن، دوباره کل منبع را درخواست کنید:
GET /myFeed
سرور پاسخ می دهد:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
<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 gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
<id>http://www.example.com/id/1</id>
<link rel='edit' href='http://example.com/myFeed/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>
</feed>
توجه: اگر فایروال شما اجازه PUT نمی دهد، یک HTTP POST انجام دهید و هدر override متد را به صورت زیر تنظیم کنید:
X-HTTP-Method-Override: PUT
حذف یک ورودی
برای حذف یک ورودی موجود، با استفاده از URI ویرایش ورودی (همانطور که سرور در مثال قبلی ارائه کرده است) یک درخواست DELETE ارسال کنید.
اگر فایروال شما اجازه DELETE را نمی دهد، یک HTTP POST انجام دهید و هدر override متد را به صورت زیر تنظیم کنید:
X-HTTP-Method-Override: DELETE
هنگامی که یک ورودی را حذف می کنید، می توانید انتخاب کنید که حذف مشروط (فقط در صورتی حذف شود که ورودی از آخرین باری که آن را بازیابی کرده اید تغییر نکرده باشد) یا حذف بدون قید و شرط. برای اطلاعات بیشتر، بخش نسخه‌سازی منابع (ETags) سند مرجع پروتکل را ببینید. برای حذف بدون قید و شرط، هدر HTTP زیر را تنظیم کنید:
If-Match: *
مثال زیر یک ورودی را حذف می کند (اگر هدرها به طور مناسب تنظیم شده باشند):
DELETE /myFeed/1/
سرور پاسخ می دهد:
200 OK
یک GET دیگر انجام دهید تا ببینید که فید اکنون حاوی هیچ ورودی نیست:
GET /myFeed
سرور با فیدی پاسخ می‌دهد که حاوی چیزی جز فراداده نیست:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<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 را در سند مرجع پروتکل ببینید.
درخواست فید یا ورودی جزئی (تجربی)
برخلاف نمونه ساده فید نشان داده شده در این سند، در عمل، فیدها می توانند بسیار پیچیده باشند. با برخی از API ها، می توانید به جای نمایش کامل منبع، فقط عناصر یا ویژگی های مورد علاقه را درخواست کنید. هنگامی که از بازیابی و تجزیه داده های غیر ضروری اجتناب می کنید، می توانید کارایی برنامه مشتری خود را به طور قابل توجهی بهبود بخشید.
برای درخواست پاسخ جزئی ، از پارامتر پرس و جو fields استفاده کنید تا مشخص کنید کدام عناصر یا ویژگی هایی را می خواهید برگردانید. برای اطلاعات بیشتر، به پاسخ جزئی در سند مرجع پروتکل مراجعه کنید.
مثال زیر فقط شناسه فید و نویسنده و عنوان را برای هر ورودی فید درخواست می کند.
GET /myFeed?fields=id,entry(author)
سرور پاسخ می دهد:
200 OK
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'>
<id>http://www.example.com/myFeed</id>
<entry>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 1</title>
</entry>
<entry>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<title type='text'>Entry 2</title>
</entry>
</feed>
می توانید از پارامتر fields برای هر نوع درخواستی که داده را برمی گرداند استفاده کنید. علاوه بر GET ، این شامل POST و PUT (و همچنین PATCH است که برای درخواست‌های به‌روزرسانی جزئی استفاده می‌شود).
توجه: پارامتر پرس و جو fields فقط داده های ارسال شده در پاسخ به درخواست را کنترل می کند. بر داده هایی که باید در متن درخواست PUT ، POST یا PATCH ارائه دهید، تأثیری نمی گذارد.
نمونه هایی برای POST و PUT در زیر نشان داده شده است.
- وقتی یک درخواست
POSTبرای یک پاسخ جزئی می‌کنید، همچنان باید همان داده‌هایی را که در درج یک ورودی جدید توضیح داده شده است ارائه دهید. مثال زیر یک پاسخ جزئی را درخواست می کند که فقط شامل عنوان ورودی جدید ایجاد شده است:POST /myFeed?fields=title ...data...سرور پاسخ می دهد:
200 OK <?xml version='1.0' encoding='utf-8'?> <entry xmlns='http://www.w3.org/2005/Atom'> <title type='text'>Entry 1</title> </entry>
- هنگامی که یک درخواست
PUTبرای یک پاسخ جزئی ارائه می کنید، همچنان باید یک نسخه اصلاح شده از نمایش کامل منبع ارائه دهید، همانطور که در به روز رسانی یک ورودی توضیح داده شده است. . مثال زیر یک پاسخ جزئی را درخواست می کند که فقط حاوی مقدار ETag جدید ورودی اصلاح شده است:PUT /myFeed/1/1?fields=@gd:etag ...data...
سرور پاسخ می دهد:
200 OK <?xml version='1.0' encoding='utf-8'?> <entry xmlns='http://www.w3.org/2005/Atom' gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>
به روز رسانی فیلدهای خاص (تجربی)
اگر API مورد استفاده شما از پاسخ جزئی پشتیبانی می‌کند و دارای فیلدهای قابل ویرایش است، می‌توانید هنگام اصلاح یک ورودی، از ارسال داده‌های غیرضروری نیز اجتناب کنید. به روز رسانی جزئی به شما امکان می دهد فقط برای فیلدهایی که می خواهید تغییر دهید داده ارسال کنید.
برای استفاده از به‌روزرسانی جزئی، یک درخواست PATCH به همان URI ویرایشی ارسال می‌کنید که با PUT استفاده می‌کنید. داده هایی که با PATCH ارسال می کنید باید از قراردادهای خاصی پیروی کنند. با این حال، معناشناسی به اندازه کافی منعطف است تا بتوانید داده ها را در منبع هدف جایگزین کنید، به آن اضافه کنید یا حتی از آن حذف کنید، همه با یک درخواست واحد.
توجه: مانند PUT ، باید ETag ورودی اصلی را مشخص کنید تا مطمئن شوید که تغییرات دیگران را بازنویسی نمی‌کنید.
برای اطلاعات بیشتر در مورد PATCH و معنای آن، به روز رسانی جزئی در سند مرجع پروتکل را ببینید.
این مثال یک درخواست به‌روزرسانی جزئی را نشان می‌دهد که عنوان ورودی را تغییر می‌دهد:
PATCH /myFeed/1/1/
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag="EksPTg1Bfyp7IWA6WhJT"
gd:fields='title'>
<title>New Title</title>
</entry> هنگامی که سرور یک درخواست PATCH دریافت می کند، ابتدا هر فیلد مشخص شده توسط ویژگی gd:fields ورودی را حذف می کند (در صورت وجود). سپس هر داده ارائه شده در بدنه درخواست را با منبع هدف ادغام می کند. در این مثال ابتدا عنصر عنوان از منبع هدف حذف می شود. سپس مقدار عنوان جدید ادغام می شود. عملاً این درخواست عنوان قدیمی را با عنوان جدید جایگزین می کند.
با این حال، توجه داشته باشید که معنای PATCH عبارت است از ادغام نمایش جزئی در منبع موجود. همیشه لازم نیست یک فیلد را حذف کنید تا مقدار آن را به روز کنید.
- اگر فیلد فقط یک بار می تواند در ورودی هدف وجود داشته باشد، پس از ادغام، فیلد در نمایش جزئی، فیلد مربوطه را در ورودی هدف بازنویسی می کند.
- اگر فیلد می تواند بیش از یک بار در ورودی هدف وجود داشته باشد، پس از ادغام، فیلد جزئی به ورودی هدف اضافه می شود.
تفاوت بین نحوه ادغام فیلدهای تکراری و غیر تکراری با مثال بعدی نشان داده شده است که یک عنوان و نویسنده جدید را بدون استفاده از ویژگی gd:fields برای حذف هر یک از آنها ابتدا به ورودی اضافه می کند.
PATCH /myFeed/1/1/
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:edtag="EksPTg1Bfyp7IWA6WhJT">
<title>A new title</title>
<author>
<name>Fitzwilliam Darcy</name>
<email>darcy@gmail.com</email>
</author>
</entry>
از آنجایی که نمایش ورودی جزئی فاقد ویژگی gd:fields است، هیچ فیلدی حذف نمی‌شود. با این حال، مقادیر جدید برای عناصر <title> و <author> با منبع هدف ادغام می شوند:
- از آنجایی که Atom در هر ورودی فقط یک عنوان را مجاز می‌کند، عنوان جدید مقدار موجود را بازنویسی می‌کند.
- از آنجایی که Atom به چندین نویسنده در هر ورودی اجازه می دهد، نویسنده جدید به لیست عناصر نویسنده که از قبل در منبع هدف قرار دارند، اضافه می شود.
توجه: همه APIها با استاندارد Atom مطابقت ندارند. به عنوان مثال، برخی از API ها فقط یک واحد را مجاز می دانند
عنصر <author>در هر ورودی. دیگران نویسنده مدخل را به ارث می برنداز سطح خوراک، زمینه را فقط خواندنی می کند.
پس از اینکه سرور یک درخواست PATCH معتبر را پردازش کرد، یک کد وضعیت HTTP 200 به همراه یک کپی از نمایش کامل ورودی به روز شده را برمی گرداند.
اگر ترجیح می دهید سرور فقط عناصر یا ویژگی های خاصی را برگرداند، می توانید از پارامتر query fields با PATCH برای درخواست پاسخ جزئی استفاده کنید.
منابع اضافی
ممکن است اسناد شخص ثالث زیر برای شما مفید باشد:
- مروری بر Atom از IBM
- تعاریف روش HTTP 1.1 ; مشخصات برای
GET،POST،PUTوDELETE - تعاریف کد وضعیت HTTP 1.1
- نحوه ایجاد پروتکل REST
- ساخت خدمات وب به روش REST
- مقدمه ای فنی بر XML
- فضاهای نام XML بر اساس مثال