متوقّفة نهائيًا: تم إيقاف واجهة برمجة تطبيقات المواقع الإلكترونية نهائيًا وقد تتوقف عن العمل في أي وقت. يمكن لواجهة برمجة تطبيقات "مواقع Google" الوصول إلى "مواقع Google" الكلاسيكية فقط. لا يمكن لواجهة برمجة تطبيقات المواقع الوصول إلى الإصدار المُعاد تصميمه من المواقع الذي تم إطلاقه في 22 تشرين الثاني (نوفمبر) 2016.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

أدوات لمواقع Google

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

كل صفحة في "مواقع Google" هي حاوية أدوات محتملة. بالإضافة إلى ذلك، تقدّم خدمة "مواقع Google" Data API التي يمكن استخدامها جنبًا إلى جنب مع أدوات لإنشاء تطبيقات قوية. وهذا يعني أنه بصفتك مطور أدوات، يمكنك الاستفادة من واجهة برمجة تطبيقات المواقع الكلاسيكية لإنشاء أدوات جذابة لمطوّري برامج الويب الآخرين وجماهيرهم، كما لاستخدامك الخاص.

عندما تنشئ أداة للمواقع، فإنها تصبح متاحة لملايين من المستخدمين النشطين المستخدمين. ما عليك سوى إرسال أداتك إلينا، وستظهر حيث يمكن للمستخدمين التصفح وتكوين وإضافة الأداة بسهولة إلى المواقع.

أنت تعرف الآن أن {sites_name_short} منصة توزيع رائعة لأداتك، فما هي تنتظر؟ ابدأ في إنشاء الأدوات للمواقع الآن!

نظرة عامة على أداة المواقع

بشكل عام، الأدوات عبارة عن أدوات مساعدة صغيرة تُنشئ معلومات خارجية أو تسحبها إلى مواقع الويب. . الأداة في أبسط صورها هي ملف .xml صغير يسترد المعلومات باستخدام والقدرة على إتاحتها على صفحات ويب متعددة في الوقت نفسه. في "مواقع Google"، بما في ذلك نتائج أداة في إطار iframe يعمل كقناة توصيل لهذه المعلومات الخارجية. لم تعُد بعض الأدوات من ذلك، هي إطارات iframe التي تمر عبر المعلومات من موقع ويب آخر.

تجمع الأدوات الأكثر تقدمًا المحتوى الديناميكي وتقدمه للتطبيقات التفاعلية ضمن صفحات مواقعك. يمكنك الاطّلاع على مثال للأداة.

تتكون الأدوات من المكونات التالية:

ملف مواصفات الأداة: ملف xml .يتضمّن دالتَي HTML وJavaScript.
صفحة الحاوية - صفحة الويب التي يتم إدراج الأداة فيها، وهي في هذه الحالة موقع من مواقع Google.
مصدر البيانات الخارجي - هذا الحقل اختياري وقد يكون في مكان ملف .xml نفسه ولكن غالبًا ما يتم استدعاؤه من خلال مواصفات الأداة على HTTP لتقديم نتائجه.

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

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

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

تحذير: أدوات تم إنشاؤها باستخدام الإصدار القديم قد تعمل واجهة برمجة التطبيقات للأدوات في "مواقع Google" ولكنها غير متوافقة رسميًا. أدوات مدمجة ومستنِدة إلى الخلاصات لا يتم دعمها بالمثل. لذلك، تنصحك Google بإنشاء جميع أدوات المواقع باستخدام الأدوات.* الحالية واجهة برمجة التطبيقات. اطّلِع على هذه المشاركة للحصول على تفسير:
http://igoogledeveloper.blogspot.com/2009/09/more-things-change-more-they-stay-same.html

مثال لأداة

إليك أداة تضمين بسيطة ولكنها شائعة، لا تقتصر فقط على توفير إطار iframe لتمرير محتوى الويب الآخر:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Include gadget (iframe)" title_url="http://sites.google.com/"
          description="Include another web page in your Google Site"
          thumbnail="https://www.gstatic.com/sites-gadgets/common/images/sites-icon-gadget-thumb.png"
          screenshot="https://www.gstatic.com/sites-gadgets/common/images/sites-icon-gadget-ss.png"
          height="800" width="600" author="Google">
    <Require feature="dynamic-height"/>
  </ModulePrefs>
  <UserPref name="iframeURL" display_name="URL to content" required="true"/>
  <UserPref name="scroll" display_name="Display scrollbar" default_value="auto" datatype="enum">
    <EnumValue value="auto" display_value="Automatic"/>
    <EnumValue value="no" display_value="No"/>
    <EnumValue value="yes" display_value="Yes"/>
  </UserPref>
  <Content type="html" view="default,canvas">
  <div id='dest'><img src="http://www.google.com/ig/images/spinner.gif"></div>
  <script type="text/javascript">
  gadgets.util.registerOnLoadHandler(doRender);

  function doRender(){
    // setup variables
    var prefs = new gadgets.Prefs();
    var iframeURL = prefs.getString('iframeURL');
    var scroll = prefs.getString('scroll');
    var height = 800;
    var width = 600;

    if (gadgets.window) {
      var viewport = gadgets.window.getViewportDimensions();
      if (viewport.width) {
        var width = viewport.width;
      }
      if (viewport.height) {
        var height = viewport.height;
      }
    }

    var iframe = document.createElement('iframe');
    iframe.setAttribute('width', width + 'px');
    iframe.setAttribute('height', height + 'px');
    iframe.setAttribute('frameborder','no');
    if(scroll){
      iframe.setAttribute('scrolling', scroll);
    }
    iframe.setAttribute('src', iframeURL);

    // set the slideshow to the placeholder div
    var dest = document.getElementById('dest');
    dest.innerHTML = '';
    dest.appendChild(iframe);
  }
  </script>
  </Content>
</Module>

راجِع البدء: الأدوات.* API للحصول على وصف كامل لعلامات الأدوات والمحتوى المتوقع.

استضافة أداتك

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

فيما يلي خيارات استضافة الأداة:

App Engine - بإمكانه تخزين جميع الملفات التي تطلبها أدواتك. يتطلّب ذلك بعض الإعدادات، وتحديدًا إنشاء المشاريع وعمليات تحميل الملفات اللاحقة. لكنها ستتدرج بسهولة مع عدد كبير من المستخدمين. يمكنك إنشاء تطبيق لتخزين جميع أدواتك وتطبيق آخر لعرض ملفات ثابتة، بما في ذلك ملف app.yaml يشبه:
```
application: <your app name>
version: 1
runtime: python
api_version: 1

handlers:
- url: /.*
  static_dir: static
```
إذا وضعت جميع ملفات الأداة في الدليل الثابت، فيمكنك تحرير الملفات في الدليل المحلي ونشرها في App Engine في كل مرة تقوم فيها بإجراء تغييرات. إذا كان لديك ملف /static/gadget.xml، فسيكون عنوان URL له كما يلي: http://<your-app-name>.appspot.com/static/gadget.xml
أي موقع جغرافي من اختيارك على الإنترنت - يخضع بالكامل لسيطرتك، ولكن أيضًا المسئولية الكاملة. قد يؤدي وقت الاستراحة على الخادم إلى انقطاع الخدمة لدى مستخدمي أدواتك.

إنشاء الأداة

أما الأدوات فهي HTML فقط، و (اختياريًا) JavaScript أو Flash أو Silverlight ومُحاطة بـ XML. يقدم دليل مطوّري الأدوات جميع التفاصيل اللازمة لإنشاء أدواتك الخاصة. بالإضافة إلى ذلك، يمكن استخدام نماذج OpenSocial لإنشاء تطبيقات اجتماعية بشكل سريع في الأدوات.

إليك الخطوات عالية المستوى لإنشاء أداة للمواقع:

حدد المكان الذي ستتم استضافة الأداة فيه. ويمكنك الاطّلاع على قسم استضافة أداتك للحصول على أوصاف للخيارات المتاحة لك.
قم بإنشاء ملف .xml جديد ليكون بمثابة المواصفات التي تريدها باستخدام محرِّر النصوص الذي تختاره.
حدِّد نوع المحتوى، إما بتنسيق HTML أو عنوان URL، وحدِّده في ملف .xml للأداة، على النحو التالي:
<Content type="html">
وسيكون ذلك غالبًا بتنسيق HTML، والذي يفترض أن كل المحتوى يتم توفيره مباشرةً في ملف xml. ولكن إذا كنت تنوي توفير المحتوى في ملف منفصل، استخدِم نوع محتوى عنوان URL. راجع اختيار نوع المحتوى للحصول على وصف كامل للاختلافات بينهما.
أنشئ محتوى في ملف .xml للأداة أو في ملفات منفصلة مستدعاة وفقًا للمواصفات. راجع قسم عرض نماذج الأدوات للتعرّف على طرق فحص الأدوات الحالية.
حدد التفضيلات الأساسية للأداة التي يمكن للمستخدمين تعديلها. راجع تحديد تفضيلات المستخدم للحصول على إرشادات. لتقديم إعدادات أكثر تقدّمًا، يُرجى الاطّلاع على قسم السماح بإعداد المستخدم المتقدّم.
حدد الإعدادات المفضّلة للوحدات التي قد يغيرها مؤلف الأداة فقط. راجع تحديد الإعدادات المفضّلة للأدوات للحصول على تفاصيل إضافية.
اختبار الأداة. راجع قسم اختبار الأداة للحصول على إرشادات.

تضمين الأداة

يمكن تضمين الأدوات في صفحات "مواقع Google" إما عن طريق تحديدها من دليل أدوات المواقع (الذي تتم مزامنته مع دليل أدوات iGoogle) أو من خلال تضمين عنوان URL الخاص بها مباشرةً.

لتضمين أداة في "مواقع Google":

انتقل إلى صفحة المواقع التي ستحتوي على الأداة الجديدة.
افتح الصفحة لإجراء التعديل.
حدد إدراج > المزيد من الأدوات
ابحث عن الأداة، واختَرها من الفئات على اليمين، أو انقر على إضافة أداة باستخدام عنوان URL والصق عنوان URL في ملف .xml. بعد ذلك، انقر على إضافة.
نصيحة: يمكن استخدام طريقة "إضافة أداة حسب عنوان URL" نفسها لتضمين الأدوات من iGoogle ومن أي مكان آخر على الإنترنت.
حدِّد أبعاد الأداة، واختَر من الإعدادات المتاحة، ثم انقر على حسنًا. تمت إضافة الأداة إلى صفحتك.
احفظ الصفحة لعرض الأداة واختبارها في الموقع.

اختبار الأداة

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

أثناء اختبار الأداة، ستكتشف حتمًا الأخطاء وستحتاج إلى إجراء تصحيحات إلى ملف .xml للأداة. يجب تعطيل التخزين المؤقت للأداة أثناء تعديل XML. وإلا، لن تظهر تغييراتك في الصفحة. يتم تخزين مواصفات الأداة مؤقتًا ما لم تطلب من المواقع عدم إجراء ذلك. لتجاوز ذاكرة التخزين المؤقت أثناء التطوير، أضِف هذا النص إلى نهاية عنوان URL لصفحة "مواقع Google" التي تحتوي على الأداة (وليس عنوان URL لملف .xml الخاص بمواصفات الأداة):

 ?nocache=1

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

بعد ذلك، راجع قسم الإعداد للنشر لنشر أداتك حتى تتمكن من إجراء اختبارات أخرى.

السماح بإعداد المستخدم المتقدّم

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

الإعدادات المفضّلة لمستخدم أداة "مواقع Google"

هناك العديد من الحالات التي تستفيد فيها الأدوات من إعدادات مفضّلة متقدّمة أكثر من تلك التي تقدّمها مكوّنات UserPref العادية. غالبًا ما يجب أن تتضمّن الإعدادات المفضّلة ميزات مثل منطق الأنشطة التجارية المخصّصة أو عمليات التحقّق أو أدوات الاختيار. تدعم الواجهة التي تم إنشاؤها من أقسام الأداة UserPref عددًا محدودًا من أنواع البيانات (سلسلة، تعداد، إلخ.)، ولذلك لا يمكن التحقق من المدخلات مثل عناوين URL أو التواريخ.

بالإضافة إلى ذلك، يمكن لمؤلفي الأدوات تمديد التهيئة كجزء من العرض القياسي في حاويات مثل iGoogle حيث يكون المشاهد والمحرِّر متطابقين تمامًا. وفي "مواقع Google"، لا يكون المشاهد هو المحرّر دائمًا، وبالتالي لا يمكن لمؤلف الأداة ضمان حصول المستخدم المعروض على إذن بتعديل الإعدادات المفضّلة. لا يمكن للحاويات الاجتماعية مثل المواقع السماح لأي مستخدم بتعديل التفضيلات، بل للمؤلف فقط.

في "مواقع Google"، يمكن استبدال الواجهة الأساسية لتفضيلات الأداة التي أنشأها UserPref بعرض الإعداد حيث يمكن توفير العديد من الإعدادات المفضّلة وأنواع البيانات الإضافية، كما في لقطة الشاشة الموضحة هنا:

عرض إعداد أداة "مواقع Google"

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

يمكن للمطوّرين استخدام واجهات برمجة تطبيقات setprefs العادية لحفظ الإعدادات المفضّلة في طريقة العرض هذه. راجع مرجع XML للأدوات وقسم حفظ الحالة في أساسيات المطوّرين للحصول على تفاصيل إضافية. وتسمح طرق العرض هذه لتطبيق الحاوية بتقديم معلومات إعداد تكميلية، ويتم إنشاؤها في ملفات مواصفات .xml للأداة بعد أقسام UserPref بعلامة افتتاحية تشبه:

  <Content type="html" view="configuration" preferred_height="150">

على سبيل المثال، تحتوي أداة news.xml التي توفّر طريقة عرض الضبط أعلاه على هذا القسم:

<Content type="html" view="configuration" preferred_height="300">
<style type="text/css">
  .config-options {
    margin: 10px;
  }
  .label {
    font-weight: bold;
    width: 35%;
    vertical-align: top;
  }
  .gray {
    color:#666666;
  }
  html {
    font-family:arial,sans-serif;
    font-size:0.81em;
    font-size-adjust:none;
    font-style:normal;
    font-variant:normal;
    font-weight:normal;
    line-height:1.5;
  }
  a:link, a:visited, a:active { text-decoration: none }
</style>
  <img alt="Google Web Elements" src="http://www.google.com/webelements/images/web_elements_logo.gif"/>
  <table class="config-options">
  <tr>
  <td align="left" class="label">Size:</td>
  <td align="left">
  <select id="size" onchange="Update()">
  <option selected="selected" value="300x250">Medium rectangle (300x250)</option>
  <option value="728x90">Leaderboard (728x90)</option>
  </select>
  </td>
  </tr>
  <tr>
  <td align="left" class="label">Select sections:</td>
  <td align="left">
  <table>
  <tbody><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_h" value="h"/> Top Stories</td>
  <td><input type="checkbox" onclick="Update()" id="sec_w" value="w"/> World</td>
  <td><input type="checkbox" onclick="Update()" id="sec_b" value="b"/> Business</td>
  </tr><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_p" value="p"/> Politics</td>
  <td><input type="checkbox" onclick="Update()" id="sec_n" value="n"/> Nation</td>
  <td><input type="checkbox" onclick="Update()" id="sec_e" value="e"/> Entertainment</td>
  </tr><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_t" value="t"/> Technology</td>
  <td><input type="checkbox" onclick="Update()" id="sec_s" value="s"/> Sports</td>
  <td><input type="checkbox" onclick="Update()" id="sec_m" value="m"/> Health</td>
  </tr></tbody>
  </table>
  </td>
  </tr>
  <tr>
  <td align="left" class="label">Or create one:</td>
  <td align="left">
  <input type="text" id="query" onchange="Update()"/>
  <br/>
  <span class="gray">Example: 2010 Olympics</span>
  </td>
  </tr>
  <tr>
  <td colspan="2">
  <div id="preview" style="margin-top:10px;overflow:auto;width:100%;">
  <iframe id="preview_ifr" frameborder="0" marginwidth="0" marginheight="0" border="0"
  style="border:0;margin:0;"
  scrolling="no" allowtransparency="true"></iframe>
  </div>
  </td>
  </tr>
  </table>
  <script type="text/javascript">
  var prefs = new gadgets.Prefs();

  function getSelectedTopics() {
    var selected = [];
    var topics = ['h', 'w', 'b', 'p', 'n', 'e', 't', 's', 'm'];
    for (var i = 0; i < topics.length; i++) {
      if (document.getElementById('sec_' + topics[i]).checked) {
        selected.push(topics[i]);
      }
    }
    return selected.join(',');
  }

  function setSelectedTopics(selected) {
    if (selected && selected.length >= 0) {
      var topics = selected.split(',');
      for (var i = 0; i < topics.length; i++) {
        document.getElementById('sec_' + topics[i]).checked = true;
      }
    }
  }

  function Update() {
    var topic = getSelectedTopics();
    var query = document.getElementById('query').value;
    var size = document.getElementById('size').value;

    var url = 'http://www.google.com/uds/modules/elements/newsshow/iframe.html?rsz=large&' +
        'format=SIZE&element=true';
    var iframe = document.getElementById('preview_ifr');
    url = url.replace(/SIZE/, size);
    if (topic.length > 0) {
      url += '&topic=' + topic;
    }
    if (query.length > 0) {
      url += '&q=' + encodeURIComponent(query);
    }
    iframe.src = url;
    if (size == '728x90') {
      iframe.style.width = '728px';
      iframe.style.height = '90px'
    } else {
      iframe.style.width = '300px';
      iframe.style.height = '250px';
    }
    prefs.set('size', size);
    prefs.set('topic', topic);
    prefs.set('query', query);
    gadgets.window.adjustHeight();
  }

  function Initialize() {
    var size = '__UP_size__';
    if (size.length > 0) {
      document.getElementById('size').value = size;
    }
    var query = '__UP_query__';
    if (query.length > 0) {
      document.getElementById('query').value = query;
    }
    setSelectedTopics('__UP_topic__');
    Update();
  }

  gadgets.util.registerOnLoadHandler(Initialize);
  </script>
  </Content>

يمكنك العثور على هذا المثال وأدوات أخرى خاصة بخدمة "مواقع Google" مع طرق عرض الإعدادات هنا:
https://www.gstatic.com/sites-gadgets/news/news.xml
http://gadgets.pardonmyzinger.org/static/qrcode.xml
https://www.gstatic.com/sites-gadgets/news/youtube_news.xml

اتباع أفضل الممارسات المتعلقة بأدوات "مواقع Google"

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

لا تضع معلومات حساسة في مواصفات الأداة أو عناوينها لأن الأداة قابلة للمشاهدة من قبل الجمهور. على سبيل المثال، لا تُدرج أسماء مشاريع داخلية.
لخفض مستوى رؤية الأداة، لا ترسلها إلى دليل أدوات iGoogle أو إلى أي خدمة قائمة عامة أخرى. بدلاً من ذلك، اجعل جميع المستخدمين يدرجونها باستخدام عنوان URL فقط. بالإضافة إلى ذلك، يمكنك إنشاء أداة من نوع عنوان URL (بدلاً من نوع HTML المعتاد الذي يتضمن كافة المحتويات) والتي تكتفي باستدعاء ملف آخر للحصول على محتوياته. عند استخدام خيار التمرير هذا، لن يظهر سوى عنوان URL للملف الثاني. راجع القسم "اختيار نوع المحتوى" ضمن "أساسيات المطوّرين" للتعرّف على الاختلافات بين أدوات HTML وعناوين URL والأدوات متاحة للجميع ضمن قسم "كتابة أدواتك الخاصة" للتعرّف على طرق أخرى لإخفاء أداتك.
والأمر الأكثر أهمية هو اختبار الأداة على عدد من المواقع المختلفة. قم بتعديل لون خلفية الموقع ولون النص وشكل الخط لضمان امتزاج أداتك مع مجموعة كبيرة من النماذج.

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