المعالجة المجمّعة في بروتوكول بيانات Google

تمنحك المعالجة المجمّعة إمكانية تنفيذ عمليات متعددة في طلب واحد، بدلاً من الاضطرار إلى إرسال كل عملية على حدة.

ملاحظة: لتنفيذ العمليات على دفعات، يجب أن تستخدم إصدارًا حديثًا من مكتبة برامج "واجهة برمجة التطبيقات لبيانات Google". لا تتوافق مكتبة برامج JavaScript مع العمليات المجمّعة.

الجمهور

هذا المستند مخصّص للمبرمجين الذين يريدون إرسال عمليات متعددة في طلب واحد باستخدام المعالجة على دفعات.

يفترض هذا المستند أنك على دراية باستخدام مكتبة عميل جافا من GData. توضح الأمثلة في هذا المستند كيفية استخدام مكتبة عميل جافا لتشغيل العمليات على دفعات.

تتعلق الأمثلة في هذا المستند بواجهة برمجة التطبيقات لبيانات Google Base. ومع ذلك، قد توفّر الخدمات الأخرى أيضًا إمكانات مجمّعة.

ملاحظة: لن يختلف البروتوكول والإجراءات العامة من مكتبات برامج أخرى، ولكن قد تختلف الطرق المحدّدة لتنفيذ الطلبات المجمّعة. يُرجى الرجوع إلى المستندات الخاصة بمكتبة العميل.

المقدمة

وباستخدام خلاصة مُجمّعة لـ GData، يمكنك جمع عمليات إدراج وإدراج وتعديل وحذف وطلب بحث متعددة، ثم إرسالها جميعًا وتنفيذها في وقت واحد.

على سبيل المثال، تتضمن الخلاصة التالية أربع عمليات:

<feed>
  <entry>
    <batch:operation type="insert"/>
    ... what to insert ...
  </entry> 
  <entry>
    <batch:operation type="update"/>
    ... what to update ...
  </entry>
  <entry>
    <batch:operation type="delete"/>
    ... what to delete ...
  </entry>
  <entry>
    <batch:operation type="query"/>
    ... what to query ...
  </entry>
</feed>

ستجري الخدمة أكبر عدد ممكن من التغييرات المطلوبة وتعرض معلومات الحالة التي يمكنك استخدامها لتقييم نجاح أو فشل كل عملية.

تحاول الخدمة تنفيذ كل عملية من العمليات على دفعة واحدة، حتى إذا لم تنجح بعض العمليات المضمّنة في المجموعة.

إرسال طلب مجمّع

يجب إرسال طلب مجمّع كمشاركة HTTP POST إلى عنوان URL مجمّع. تدعم الخلاصات المختلفة عمليات دفع مختلفة. تدعم الخلاصات المخصصة للقراءة فقط طلبات البحث فقط.

يمكنك البحث عن الخلاصة لمعرفة ما إذا كانت خلاصة معيّنة تتيح إجراء عمليات مجمّعة. إذا كانت الخلاصة تتضمن علاقة "دفعة" على مستوى الخلاصة، يشير ذلك إلى أنّ الخلاصة تتوافق مع العمليات المجمّعة.

علاقة الرابط "دُفعة" هي عنصر <link> يتضمّن السمة rel="http://schemas.google.com/g/2005#batch". تحدد السمة href لعلاقة الرابط عنوان URL حيث يمكن نشر مستندات الخلاصة لعمليات التشغيل المجمّع.

على سبيل المثال، في حال تنفيذ الإجراء: GET http://www.google.com/base/feeds/items (خلاصة "عناصر" Google Base العادية)، قد تحصل على الاستجابة التالية:

<feed xmlns=...
  <id>http://www.google.com/base/feeds/items</id>
  <link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.google.com/base/feeds/items"/>
  <link rel="http://schemas.google.com/g/2005#post"
    type="application/atom+xml"
    href="http://www.google.com/base/feeds/items"/>
  <link rel="http://schemas.google.com/g/2005#batch"
    type="application/atom+xml"
    href="http://www.google.com/base/feeds/items/batch"/>
  ...
</feed>

في هذا المثال، يكون عنوان URL المجمّع هو http://www.google.com/base/feeds/items/batch.

كتابة خلاصة عمليات مجمعة

تحتوي خلاصة العمليات على قائمة من الإدخالات لإدراجها أو تحديثها أو حذفها أو طلب بحث. يتم تحديد كل عملية من خلال عنصر <batch:operation type="insert|update|delete|query"/>.

يمكن أن يكون هذا العنصر عنصرًا ثانويًا مباشرًا لعنصر <feed> أو عنصرًا ثانويًا مباشرًا لأي من الإدخالات في الخلاصة أو كليهما. وعند تضمينه في إدخال، يحدّد العملية المطلوب تنفيذها لهذا الإدخال المحدّد. عند تضمين هذا العنصر في الخلاصة، يحدّد العملية التلقائية المطلوب تنفيذها على أي إدخالات لا تحتوي على عنصر <batch:operation/>.

عندما لا يحدد الإدخال أو الخلاصة عملية، تكون العملية التلقائية هي insert.

يجب ألا تطبق التطبيقات عمليات متعددة على الإدخال نفسه في خلاصة واحدة مجمّعة. تكون النتائج غير مُحدَّدة إذا حددت عمليات متعددة للإدخال نفسه.

لتحسين الأداء، قد لا تتم معالجة العمليات بالترتيب الذي تم طلبها به. ومع ذلك، تكون النتيجة النهائية هي نفسها دائمًا إذا تمت معالجة الإدخالات بالترتيب.

يجب ألا يزيد عدد وحدات البايت التي ترسلها إلى الخادم عن 1 ميغابايت (1,048,576 بايت). بشكل عام، لا تُفرَض أي قيود على عدد العمليات التي يمكنك طلبها طالما أن إجمالي حجم البايت لا يتجاوز 1 ميغابايت. ومع ذلك، قد تفرض بعض الخدمات قيودًا إضافية.

لاستخدام العمليات المجمّعة، يجب إضافة تعريف مساحة الاسم المجمّعة كسمة إلى العنصر <feed>:

<feed 
  xmlns="http://www.w3.org/2005/Atom"
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  ...
  xmlns:batch="http://schemas.google.com/gdata/batch">

إدراج العمليات

يتم تعريف عملية الإدراج على النحو التالي:

<batch:operation type="insert">

تعادل عملية الإدراج نشر المشاركة. عند نجاح العملية، يتم عرض محتوى الإدخال بالكامل، مع تحديث عنصر <id> في المستند وعنصر <batch:status code="201"/>.

في ما يلي مثال لطلب إدراج ناجح:

<entry>
  <title type="text">...</title>
  <content type="html">...</content>
  <batch:id>itemA</batch:id>
  <batch:operation type="insert"/>
  <g:item_type>recipes</g:item_type>
  ... 
</entry>

في ما يلي مثال للرد على طلب إدراج ناجح:

<entry>
  <batch:status code="201"/>
  <batch:id>itemA</batch:id>
  <batch:operation type="insert"/>
  <id>http://www.google.com/base/feeds/items/17437536661927313949</id>
  <link rel="self" type="application/atom+xml"
    href="http://www.google.com/base/feeds/items/17437536661927313949"/>
  <title type="text">...</title>
  <content type="html">...</content>
  <g:item_type>recipes</g:item_type>
  ... 
</entry>

تعديل العمليات

<batch:operation type="update">

تعادل عملية التحديث تنفيذ PUT على عنوان URL الذي يشير إليه العنصر <id> للإدخال. عند نجاح العملية، يتم عرض محتوى الإدخال بأكمله مع عنصر <batch:status code="200"/>.

ملاحظة: من خلال خلاصات معيّنة، عليك أيضًا تحديد رابط rel="edit" الخاص بالإدخال مع طلبات تعديل مجمّع. وهذا يشمل الخلاصات التي تتوافق مع الإصدار الأول من بروتوكول Google Data لبروتوكول التزامن المحسَّن، وتلك الخلاصات التي لا تحتوي على أرقام تعريف هي عناوين URL.

في ما يلي مثال على طلب تعديل:

<entry>
  <id>http://www.google.com/base/feeds/items/17437536661927313949</id>
  <batch:operation type="update"/>
  ...
</entry>

في ما يلي مثال على رد ناجح:

<entry>
  <batch:status code="200"/>
  <id>http://www.google.com/base/feeds/items/17437536661927313949</id>
  <batch:operation type="update"/>
  ... 
</entry>

ملاحظة: تستخدم بعض الخلاصات علامات ETags قوية لمنعك من إجراء تغييرات غير مقصودة عن طريق شخص آخر. عند تقديم طلب تعديل مجمّع لإدخال في إحدى هذه الخلاصات، يجب تقديم قيمة ETag في السمة gd:etag الخاصة بالإدخال. على سبيل المثال، <entry gd:etag="'F08NQAxFdip7IWA6WhVR'">...<batch:operation type="update"/>...

عمليات التحديث الجزئية

بالنسبة إلى الخلاصات التي تتيح إجراء تحديثات جزئية، يمكنك أيضًا استخدامها في طلبات مجمّعة. تعادل عملية التحديث الجزئي تنفيذ PATCH على عنوان URL الذي يشير إليه العنصر <id> للإدخال. عند نجاح العملية، يتم عرض محتوى الإدخال بأكمله مع عنصر <batch:status code="200"/>.

ملاحظة: من خلال خلاصات معيّنة، عليك أيضًا تحديد رابط rel="edit" الخاص بالإدخال مع طلبات تعديل مجمّع. وهذا يشمل الخلاصات التي تتوافق مع الإصدار الأول من بروتوكول Google Data لبروتوكول التزامن المحسَّن، وتلك الخلاصات التي لا تحتوي على أرقام تعريف هي عناوين URL.

<batch:operation type="patch"/>

في ما يلي مثال على طلب تعديل جزئي:

<entry gd:fields="content" gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <id>http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID</id>
  <batch:operation type="patch"/>
  <title>New title</title>
</entry>

في ما يلي مثال للاستجابة الناجحة:

<entry gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <batch:status code="200"/>
  <id>http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID</id>
  <batch:operation type="patch"/>
  <title>New title</title>
  <content></content>
  ...rest of the entry...
</entry>

حذف عمليات

<batch:operation type="delete">

تعادل عملية الحذف تنفيذ DELETE على عنوان URL الذي يشير إليه العنصر <id> في الإدخال. بالنسبة إلى عملية الحذف، ما عليك سوى إرسال العنصر <id> لحذف الإدخال. وسيتم تجاهل أي معلومات أخرى تقدمها في العناصر غير المتوفِّرة في مساحة الاسم batch:. عند نجاح العملية، سيتم عرض إدخال بالمعرف نفسه مع عنصر <batch:status code="200"/>.

ملاحظة: مع خلاصات معيّنة، عليك أيضًا تحديد رابط rel="edit" للإدخال باستخدام طلبات الحذف المجمّع. وهذا يشمل الخلاصات التي تتوافق مع الإصدار الأول من بروتوكول Google Data لبروتوكول التزامن المحسَّن، وتلك الخلاصات التي لا تحتوي على أرقام تعريف هي عناوين URL.

في ما يلي مثال على طلب حذف:

<entry>
  <batch:operation type="delete"/>
  <id>http://www.google.com/base/feeds/items/17437536661927313949</id>
</entry>

في ما يلي مثال على رد ناجح:

<entry>
  <batch:operation type="delete"/>
  <id>http://www.google.com/base/feeds/items/17437536661927313949</id>
  <batch:status code="200" reason="Success"/>
</entry>

ملاحظة: تستخدم بعض الخلاصات علامات ETags قوية لمنعك من إجراء تغييرات غير مقصودة عن طريق شخص آخر. عند تقديم طلب حذف مجمّع لإدخال في إحدى هذه الخلاصات، يجب تقديم قيمة ETag في السمة gd:etag الخاصة بالإدخال. على سبيل المثال، <entry gd:etag="'F08NQAxFdip7IWA6WhVR'">...<batch:operation type="delete"/>...

عمليات طلب البحث

<batch:operation type="query">

تعادل عملية طلب البحث تنفيذ GET على عنوان URL الذي يشير إليه العنصر <id> للإدخال. عند نجاح العملية، يتم عرض محتوى الإدخال بالكامل.

ملاحظة: من خلال خلاصات معيّنة، عليك أيضًا تحديد الرابط rel="self" الخاص بالطلب من خلال طلبات بحث مجمّعة. ويشمل ذلك الخلاصات التي لا تتضمّن معرّفات تشكّل عناوين URL.

في ما يلي مثال لطلب بحث:

<entry>
  <id>http://www.google.com/base/feeds/items/1743753666192313949</id>
  <batch:operation type="query"/>
</entry>

في ما يلي مثال على رد ناجح:

<entry>
  <id>http://www.google.com/base/feeds/items/1743753666192313949</id>
  <batch:operation type="query"/>
  <batch:status code="200" reason="Success"/>
   ...
</entry>

عمليات التتبع

لا يتم بالضرورة عرض نتائج إدخال GData بنفس ترتيب الطلب. يمكنك تتبع عملية على مدار عمرها باستخدام معرّف.

بالنسبة إلى عمليات التحديث والحذف والاستعلام، يمكنك استخدام رقم تعريف الإدخال نفسه لتتبع العملية.

بالنسبة إلى عمليات الإدراج، نظرًا لعدم وجود معرّف بعد، يمكنك تمرير معرّف العملية. يمكن استخدام هذا المعرّف لربط إدخالات النتائج بإدخالات الطلب. يتم تمرير معرِّف العملية في العنصر <batch:id>.

بالنسبة إلى كل عملية، تعرض GData استجابة تفيد ما إذا كانت العملية ناجحة أو ناجحة. يحدد كل رد الإدخال ذي الصلة. يتم دائمًا عرض معرّف الإدخال لإجراء عملية تحديث أو حذف أو طلب بحث أو عملية إدراج ناجحة. وإذا حددت معرّفًا مجمّعًا، فسيتم عرض هذا المعرّف أيضًا. ونظرًا لأن عمليات الإدراج غير الناجحة ليس لها معرّف إدخال مقترن بها، فسيتم عرض معرّف المجموعة فقط.

وباستخدام معرّف كل عملية، يمكنك إعادة محاولة العمليات التي تعذّر تنفيذها فقط، بدلاً من إعادة إرسال دفعة العمليات بالكامل.

محتوى <batch:id> هو قيمة سلسلة يتم تعريفها بواسطة العميل وسيتم تكرارها في إدخال الاستجابة المقابل.يمكنك تحديد أي قيمة تساعد العميل في ربط الاستجابة بالإدخال في الطلب الأصلي. سيتم تكرار هذا العنصر كما هو في الإدخال المقابل، حتى إذا أخفقت العملية. لا تخزّن خدمة GData محتوى معرّف المجموعة هذا أو تفسره مطلقًا.

يوضح المثال التالي خلاصة العمليات المجمعة. لاحظ أن العنصر <batch:id> يصنف هذه العملية كـ itemB.

<entry>
  <title type="text">...</title>
  <content type="html">...</content>
  <batch:id>itemB</batch:id>
  <batch:operation type="insert"/>
  <g:item_type>recipes</g:item_type>
</entry>

يوضح المثال التالي إدخال الحالة المجمّعة الذي يتم عرضه استجابة لهذه العملية.

<entry>
  <id>http://www.google.com/base/feeds/items/2173859253842813008</id>
  <published>2006-07-11T14:51:43.560Z</published>
  <updated>2006-07-11T14:51: 43.560Z</updated>
  <title type="text">...</title>
  <content type="html">...</content>
  <link rel="self" 
    type="application/atom+xml" 
    href="http://www.google.com/base/feeds/items/2173859253842813008"/>
  <link rel="edit" 
    type="application/atom+xml" 
    href="http://www.google.com/base/feeds/items/2173859253842813008"/>
  <g:item_type>recipes</g:item_type>
  <batch:operation type="insert"/>
  <batch:id>itemB</batch:id>
  <batch:status code="201" reason="Created"/>
</entry>

التعامل مع رموز الحالة

يتم التعبير عن رموز الحالة من خلال العنصر التالي:

<batch:status code="200|201|404|500|..." reason="reason" [content-type="type"]/>

يحتوي كل إدخال في خلاصة الردود على عنصر <batch:status> واحد. يصف هذا العنصر ما حدث أثناء تنفيذ العملية. وهو يحاكي استجابة HTTP التي كان سيتم إرسالها إذا تم إرسال العملية بشكل فردي، بدلاً من كجزء من خلاصة مجمعة.

يجب التحقق من العنصر <batch:status> لكل إدخال في الاستجابة لمعرفة ما إذا تمت معالجة العملية المرتبطة بنجاح. تحتوي السمة code="n" على رمز حالة GData.

أوصاف الحالة

تحتوي السمة reason="reason" للعنصر <batch:status> على شرح أكثر تفصيلاً لحالة العملية.

نوع المحتوى

تحتوي السمة content-type="type" للعنصر <batch:status> على نوع MIME للبيانات المضمَّنة في العنصر <batch:status>. ويتوافق هذا مع رأس Content-Type لاستجابة حالة HTTP. هذه السمة اختيارية.

عند ضبط نوع المحتوى، يصف نص العنصر <batch:status> الخطأ الذي حدث أثناء معالجة الإدخال.

تحديد العمليات المتقطعة

يتم تضمين العنصر التالي في استجابة عملية تمت مقاطعتها:

<batch:interrupted reason="reason" success="N" failures="N" parsed="N">

ويعني هذا العنصر أنّه تمّت معالجة المعالجة المجمّعة وأخفقت جميع محاولات استعادة سبب الانقطاع. ربما تمت معالجة بعض الإدخالات بنجاح. وقد تم التخلي عن جميع الإدخالات التي لم يتم الإبلاغ عنها تفيد بنجاحها قبل هذه المرحلة.

هذا العنصر غير عادي جدًا ويشير عادةً إلى أنّ الخلاصة التي تم إرسالها في نص الطلب لم تكن بتنسيق XML صحيح.

وكما هو الحال مع العنصر <batch:status>، يمكن العثور على رمز حالة قصير في السمة reason. وقد يتم أيضًا العثور على استجابة أطول داخل العنصر.

مثال على العمليات المجمّعة وخلاصات الحالة

إليك خلاصة عمليات مجمّعة يمكن إرسالها إلى الخادم. تطلب هذه الخلاصة من الخادم حذف إدخالين وإضافة إدخالين جديدين. تجدر الإشارة إلى أنّ العنصر <feed> يجب أن يتضمّن تقسيم مساحة اسم للدُفعة، على النحو الموضّح في المثال أدناه.

POST : http://www.google.com/base/feeds/items/batch
<?xml version="1.0" encoding="UTF-8"?>
<feed
  xmlns="http://www.w3.org/2005/Atom"
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:g="http://base.google.com/ns/1.0"
  xmlns:batch="http://schemas.google.com/gdata/batch">
  <title type="text">My Batch Feed</title>
  <entry>
    <id>http://www.google.com/base/feeds/items/13308004346459454600</id>
    <batch:operation type="delete"/>
  </entry>
  <entry>
    <id>http://www.google.com/base/feeds/items/17437536661927313949</id>
    <batch:operation type="delete"/>
  </entry>
  <entry>
    <title type="text">...</title>
    <content type="html">...</content>
    <batch:id>itemA</batch:id>
    <batch:operation type="insert"/>
    <g:item_type>recipes</g:item_type>
  </entry>
  <entry>
    <title type="text">...</title>
    <content type="html">...</content>
    <batch:id>itemB</batch:id>
    <batch:operation type="insert"/>
    <g:item_type>recipes</g:item_type>
  </entry>
</feed>

لنفترض أن الإدخالين نجحان، ولكن أخفقت إحدى عمليتي الحذف. في هذه الحالة، قد تبدو خلاصة حالة الدفعة على النحو التالي. لاحظ أنّه تمّت إعادة ترتيب الإدخالات مقارنةً بخلاصة العمليات المجمّعة.

<?xml version="1.0" encoding="UTF-8"?>
<feed
  xmlns="http://www.w3.org/2005/Atom"
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:g="http://base.google.com/ns/1.0"
  xmlns:batch="http://schemas.google.com/gdata/batch">
  <id>http://www.google.com/base/feeds/items</id>
  <updated>2006-07-11T14:51:42.894Z</updated>
  <title type="text">My Batch</title>
  <link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.google.com/base/feeds/items"/>
  <link rel="http://schemas.google.com/g/2005#post"
    type="application/atom+xml"
    href="http://www.google.com/base/feeds/items"/>
  <link rel=" http://schemas.google.com/g/2005#batch"
    type="application/atom+xml"
    href="http://www.google.com/base/feeds/items/batch"/>
  <entry>
    <id>http://www.google.com/base/feeds/items/2173859253842813008</id>
    <published>2006-07-11T14:51:43.560Z</published>
    <updated>2006-07-11T14:51: 43.560Z</updated>
    <title type="text">...</title>
    <content type="html">...</content>
    <link rel="self"
      type="application/atom+xml"
      href="http://www.google.com/base/feeds/items/2173859253842813008"/>
    <link rel="edit"
      type="application/atom+xml"
      href="http://www.google.com/base/feeds/items/2173859253842813008"/>
    <g:item_type>recipes</g:item_type>
    <batch:operation type="insert"/>
    <batch:id>itemB</batch:id>
    <batch:status code="201" reason="Created"/>
  </entry>
  <entry>
    <id>http://www.google.com/base/feeds/items/11974645606383737963</id>
    <published>2006-07-11T14:51:43.247Z</published>
    <updated>2006-07-11T14:51: 43.247Z</updated>
    <title type="text">...</title>
    <content type="html">...</content>
    <link rel="self"
      type="application/atom+xml"
      href="http://www.google.com/base/feeds/items/11974645606383737963"/>
    <link rel="edit"
      type="application/atom+xml"
      href="http://www.google.com/base/feeds/items/11974645606383737963"/>
    <g:item_type>recipes</g:item_type>
    <batch:operation type="insert"/>
    <batch:id>itemA</batch:id>
    <batch:status code="201" reason="Created"/>
  </entry>
  <entry>
    <id>http://www.google.com/base/feeds/items/13308004346459454600</id>
    <updated>2006-07-11T14:51:42.894Z</updated>
    <title type="text">Error</title>
    <content type="text">Bad request</content>
    <batch:status code="404"
      reason="Bad request"
      content-type="application/xml">
      <errors>
        <error type="request" reason="Cannot find item"/>
      </errors>
    </batch:status>
  </entry>
  <entry>
    <id>http://www.google.com/base/feeds/items/17437536661927313949</id>
    <updated>2006-07-11T14:51:43.246Z</updated>
    <content type="text">Deleted</content>
    <batch:operation type="delete"/>
    <batch:status code="200" reason="Success"/>
  </entry>
</feed>

استخدام الوظيفة المجمّعة لمكتبة عميل GData Java

يوضح هذا القسم كيفية استخدام وظيفة مكتبة مكتبة جافا لـ GData لإرسال مجموعة من طلبات الإدراج و/أو التحديث و/أو الحذف.

تستخدم الأمثلة الواردة في هذا القسم واجهات برمجة تطبيقات Google Base.

استورد الفئات التي ستحتاج إليها أولاً، بالإضافة إلى فئات GData العادية وGoogle Base:

import com.google.gdata.data.batch.*;
import com.google.api.gbase.client.*;

لإرسال طلب مجمّع، يجب الحصول على عنوان URL المجمّع من خلاصة. يوضّح مقتطف الرمز التالي كيفية إجراء ذلك، بافتراض أن feed هو كائن GoogleBaseFeed يحتوي على معلومات حول خلاصة:

Link batchLink = feed.getLink(Link.Rel.FEED_BATCH, Link.Type.ATOM);
if (batchLink != null) {
  URL batchUrl = new URL(batchLink.getHref());
  ... // batch handling
} else {
  // batching is not supported for this feed
}

يُعد مقتطف الشفرة التالي خلاصة تدرج إدخالين في عملية واحدة:

GoogleBaseEntry entry1 = new GoogleBaseEntry();
...   // initialize entry 1 content
BatchUtils.setBatchId(entry1, "A"); // A is the local batch ID for this entry
feed.addEntry(entry1);
GoogleBaseEntry entry2 = new GoogleBaseEntry();
... // initialize entry 2 content
BatchUtils.setBatchId(entry2, "B"); // B is the local batch ID for this entry
feed.addEntry(entry2);

لا يشير الرمز في هذا المثال أبدًا بشكل صريح إلى أن العملية المراد إجراؤها لهذه الإدخالات هي insert. ولست بحاجة إلى تحديد ذلك صراحةً، لأن الإدراج هو العملية التلقائية.

لإرسال خلاصة مجمّعة وتلقّي النتائج، عليك استدعاء طريقة Service.batch.

مثل Service.insert، يعرض Service.batch الإدخالات المدرجة مع تعيين قيم <atom:id> جديدة. ويتم تضمين الإدخالات المعروضة في كائن GoogleBaseFeed.

إذا كنت تريد حذف إدخال ثالث (سبق لك جلبه وتخزينه في entry3) في الوقت نفسه الذي تُدخل فيه الإدخالين الآخرين، يمكنك استخدام الرمز التالي:

GoogleBaseEntry toDelete = new GoogleBaseEntry();


toDelete.setId(entry3.getId());
BatchUtils.setBatchOperationType(toDelete, BatchOperationType.DELETE);

feed.addEntry(toDelete);


GoogleBaseFeed result = service.batch(batchUrl, feed);

في ما يلي مثال service على com.google.gdata.client.Service.

إذا كنت تريد تعديل أحد الإدخالات، اختَر OperationType.UPDATE واضبط الإدخال بالتغييرات المطلوبة بدلاً من تركه فارغًا في الغالب.

تستخدم هذه الأمثلة واجهة برمجة التطبيقات لبيانات Google Base. إذا كنت تستخدم service.batch مع نوع آخر من خدمات GData، يمكنك استبدال الفئات GoogleBaseFeed وGoogleBaseEntry وGoogleBaseService بالخلاصة المناسبة وإدخالات الخدمة وفئاتها.

لا يتم بالضرورة عرض نتائج العملية المجمعة بالترتيب الذي تم طلبها به. في المثال أعلاه، قد تحتوي خلاصة النتائج على entry2 جيدًا متبوعًا بـ entry1. يجب ألا تفترض مطلقًا أنه يتم إرجاع الإدخالات بأي ترتيب معيّن.

يجب أن تعين خلاصة عمليات المعالجة معرّفًا مجمعًا فريدًا لكل عملية إدراج، كما هو موضح في عمليات التتبع. في الأمثلة أعلاه، معرّفا المجموعتين هما A وB. لذلك، للعثور على حالة العمليات المطلوبة، يجب تكرار الإدخالات في خلاصة الدفعة المعروضة ومقارنة معرّف المجموعة أو معرّف المجموعة، كما يلي:

for (GoogleBaseEntry entry : result.getEntries()) {
  String batchId = BatchUtils.getBatchId(entry);      
  if (BatchUtils.isSuccess(entry)) {     
    if ("A".equals(batchId)) {       
      entry1 = entry;     } 
    else if ("B".equals(batchId)) {       
      entry2 = entry;     } 
    else if (BatchUtils.getBatchOperationType(entry) 
      == BatchOperationType.DELETE) {       
      System.out.println("Entry " + entry.getId() +
      " has been deleted successfully.");     
    }      
  } else {     
    BatchStatus status = BatchUtils.getBatchStatus(entry);     
    System.err.println(batchId + " failed (" +                
      status.getReason() + ") " +  status.getContent());      
    }    
  }

إنّ كل عنصر يظهر في الخلاصة المعروضة يتضمّن عنصر BatchStatus مرتبطًا به. يحتوي الكائن BatchStatus على رمز عرض HTTP واستجابة توضّح الخطأ الذي حدث أثناء معالجة الإدخال. يلزمك التحقق من رمز عرض HTTP لكل إدخال لمعرفة ما إذا كانت العملية قد نجحت أم لا.

ويتم التحقّق في المثال أعلاه باستخدام الطريقة المناسبة BatchUtils.isSuccess. في هذه الحالة، يعادل الرقم BatchUtils.getBatchStatus(entry) < 300.

يتم توضيح رموز الحالة والردود في معالجة رموز الحالة.

الرجوع إلى الأعلى