مقتطفات رمز واجهة برمجة التطبيقات للبيانات

التعليمات

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

تنفيذ طلبات واجهة برمجة التطبيقات

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

تبديل مقتطفات الشفرة والنماذج الكاملة

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

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

تشغيل نماذج الرموز البرمجية بالكامل محليًا

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

جافا

المتطلبات الأساسية

  • جافا الإصدار 1.7 أو أحدث
  • Gradle 2.3 أو إصدار أحدث

إعداد مشروعك وتشغيل نماذج التعليمات البرمجية

  1. أنشئ مشروعًا في وحدة تحكم واجهة برمجة التطبيقات وأنشئ بيانات اعتماد لتطبيق ويب. اضبط معرِّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه على النحو المناسب.

  2. اتبع الإرشادات في دليل البدء السريع لجافا سكريبت لواجهة برمجة التطبيقات لإعداد مشروعك، ولكن استبدل محتويات ملف build.gradle الافتراضي بالرمز التالي:

    apply plugin: 'java'
apply plugin: 'application'

mainClassName = 'ApiExample'
sourceCompatibility = 1.7
targetCompatibility = 1.7
version = '1.0'

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.google.api-client:google-api-client:1.22.0'
    compile 'com.google.oauth-client:google-oauth-client-jetty:1.22.0'
    compile 'com.google.apis:google-api-services-youtube:v3-rev182-1.22.0'
    compile group: 'com.google.code.gson', name: 'gson', version: '1.7.2'
    compile group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.4.4'
}

compileJava {
    options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"
}

  3. من دليل العمل، احفظ ملف client_secrets.json المرتبط ببيانات الاعتماد على src/main/resources/client_secret.json.

  4. من دليل العمل، انسخ نموذج الرمز الكامل إلى src/main/java/ApiExample.java. (اسم الفئة في كل نموذج هو ApiExample بحيث لا تحتاج إلى تعديل ملف build.gradle لتشغيل نماذج مختلفة.)

  5. شغّل النموذج من سطر الأوامر:

    gradle -q run

  6. تطبع معظم النماذج شيئًا إلى STDOUT. يمكنك أيضًا الاطلاع على موقع YouTube على الويب لمشاهدة تأثيرات الطلبات التي تكتب البيانات، مثل الطلبات التي تنشئ قوائم تشغيل أو أقسام للقناة.

جافا سكريبت

  1. أنشئ مشروعًا في وحدة تحكم واجهة برمجة التطبيقات وأنشئ بيانات اعتماد لتطبيق ويب. عيّن مصادر JavaScript المعتمدة لتحديد عنوان URL الذي سترسل منه الطلبات (على سبيل المثال http://localhost).

  2. انسخ نموذج الرمز بالكامل إلى ملف محلي يمكن لخادم الويب الوصول إليه (مثل /var/www/html/example.html).

  3. ابحث عن السطر في نموذج الرمز الذي يحدِّد معرِّف العميل لاستخدامه في الطلب، واستبدِل القيمة بمعرِّف العميل لبيانات الاعتماد:

    gapi.client.init({
    'clientId': 'REPLACE_ME',

  4. افتح الملف في متصفّحك (مثل http://localhost/example.html). من المستحسن استخدام متصفّح يتضمّن وحدة تحكّم لتصحيح الأخطاء، مثل Google Chrome.

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

Node.js

المتطلبات الأساسية

  • يجب تثبيت Node.js.
  • أداة إدارة الحزم npm (تتوفر مع Node.js).
  • مكتبة برامج "Google APIs" لنظام Node.js: 
    npm install googleapis --save
  • الدخول إلى الإنترنت ومتصفح الويب.
  • حساب Google.

إعداد مشروعك وتشغيل نماذج التعليمات البرمجية

  1. يمكنك إنشاء مشروع في وحدة تحكم واجهة برمجة التطبيقات وإعداد بيانات اعتماد OAuth 2.0 في وحدة تحكم واجهة برمجة تطبيقات Google. عند إعداد بيانات الاعتماد، اضبط نوع التطبيق على Other.

  2. احفظ ملف client_secret.json المرتبط ببيانات اعتمادك في ملف محلي.

  3. انسخ نموذج الرمز بالكامل إلى ملف محلي في الدليل نفسه الذي يحتوي على الملف client_secret.json (أو عدِّل النموذج لتحديد موقع هذا الملف بشكل صحيح).

  4. شغّل النموذج من سطر الأوامر:

    node sample.js

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

Python

المتطلبات الأساسية

  • Python 2.6 أو إصدار أحدث
  • أداة إدارة الحزمات
  • مكتبة برامج "Google APIs" للغة Python: 
    pip install --upgrade google-api-python-client
  • google-auth وgoogle-auth-oauthlib وgoogle-auth-httplib2 لتفويض المستخدم. 
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • إطار عمل تطبيق الويب Flask Python (في حال تشغيل نماذج Python لتطبيقات خادم الويب) 
    pip install --upgrade flask
  • تطلب مكتبة HTTP. 
    pip install --upgrade requests

إعداد مشروعك وتشغيل نماذج التعليمات البرمجية

  1. يمكنك إنشاء مشروع في وحدة تحكم واجهة برمجة التطبيقات وإعداد بيانات اعتماد OAuth 2.0 في وحدة تحكم واجهة برمجة تطبيقات Google. عند إعداد بيانات الاعتماد، يمكنك إعداد نوع التطبيق على تطبيق الويب للعينات التي تستخدم إطار عمل تطبيق الويب Flask Python وكذلك تعيين معرِّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لبيانات الاعتماد هذه. وبخلاف ذلك، يمكنك ضبط نوع التطبيق على غير ذلك.

  2. احفظ ملف client_secret.json المرتبط ببيانات اعتمادك في ملف محلي.

  3. انسخ نموذج الرمز بالكامل إلى ملف محلي في الدليل نفسه الذي يحتوي على الملف client_secret.json (أو عدِّل النموذج لتحديد موقع هذا الملف بشكل صحيح).

  4. شغّل النموذج من سطر الأوامر:

    python sample.py
    ملاحظة عن أمثلة تطبيقات خادم الويب:

    في حال تشغيل نماذج Python لتطبيقات خادم الويب، سيؤدي تشغيل النص البرمجي إلى بدء تشغيل خادم ويب محلي. لتنفيذ طلب البيانات من واجهة برمجة التطبيقات، يجب الانتقال إلى صفحة الويب المعروضة في المتصفّح. على سبيل المثال، تحتوي نماذج Python التي تستخدم إطار عمل تطبيق الويب Flask على سطر على النحو التالي:

    app.run('localhost', 8080, debug=True)

    تبدأ هذه الشفرة خادم ويب محلي على http://localhost:8080. ومع ذلك، لا يحاول النص البرمجي تنفيذ طلب واجهة برمجة تطبيقات إلى أن تنتقل فعليًا إلى http://localhost:8080 في متصفح. (يجب أيضًا ضبط عنوان URL للخادم المحلي كعنوان URL مُعتمَد لإعادة التوجيه لبيانات اعتماد التفويض.)

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

PHP

المتطلبات الأساسية

  • لغة PHP الإصدار 5.4 أو الأحدث مع تثبيت واجهة سطر الأوامر (CLI) وإضافة JSON.
  • أداة إدارة تبعية الملحّن.
  • مكتبة برامج "Google APIs" للغة PHP: 
    php composer.phar require google/apiclient:^2.0

إعداد مشروعك وتشغيل نماذج التعليمات البرمجية

  1. يمكنك إنشاء مشروع في وحدة تحكم واجهة برمجة التطبيقات وإعداد بيانات اعتماد OAuth 2.0 في وحدة تحكم واجهة برمجة تطبيقات Google. عند إعداد بيانات الاعتماد، اضبط نوع التطبيق على Other.

  2. احفظ ملف client_secret.json المرتبط ببيانات اعتمادك في ملف محلي.

  3. انسخ نموذج الرمز بالكامل إلى ملف محلي في الدليل نفسه الذي يحتوي على الملف client_secret.json (أو عدِّل النموذج لتحديد موقع هذا الملف بشكل صحيح).

  4. شغّل النموذج من سطر الأوامر:

    php sample.php

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

روبية

المتطلبات الأساسية

  • روبي 2.0 أو أحدث
  • مكتبة برامج "واجهة Google APIs" للغة Ruby: 
    gem install google-api-client

إعداد مشروعك وتشغيل نماذج التعليمات البرمجية

  1. يمكنك إنشاء مشروع في وحدة تحكم واجهة برمجة التطبيقات وإعداد بيانات اعتماد OAuth 2.0 في وحدة تحكم واجهة برمجة تطبيقات Google. عند إعداد بيانات الاعتماد، اضبط نوع التطبيق على Other.

  2. احفظ ملف client_secret.json المرتبط ببيانات اعتمادك في ملف محلي.

  3. انسخ نموذج الرمز بالكامل إلى ملف محلي في الدليل نفسه الذي يحتوي على الملف client_secret.json (أو عدِّل النموذج لتحديد موقع هذا الملف بشكل صحيح).

  4. شغّل النموذج من سطر الأوامر:

    ruby sample.rb

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

انتقال

  1. يمكنك إنشاء مشروع في وحدة تحكم واجهة برمجة التطبيقات وإعداد بيانات اعتماد OAuth 2.0 في وحدة تحكم واجهة برمجة تطبيقات Google. عند إعداد بيانات الاعتماد، اضبط نوع التطبيق على Other.

  2. احفظ ملف client_secret.json المرتبط ببيانات اعتمادك في ملف محلي.

  3. انسخ نموذج الرمز بالكامل إلى ملف محلي في الدليل نفسه الذي يحتوي على الملف client_secret.json (أو عدِّل النموذج لتحديد موقع هذا الملف بشكل صحيح).

  4. شغّل النموذج من سطر الأوامر:

    go run sample.go

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

استخدام الدوال النموذجية

كما ورد أعلاه، تستخدم نماذج الرموز الكاملة رمزًا معياريًا لتفويض وإنشاء طلبات واجهة برمجة التطبيقات. على سبيل المثال، تستخدم الدالة build_resource في نماذج Python قاموسًا يعيّن خصائص المورد إلى قيمها لإنشاء مورد يمكن إدراجه أو تحديثه. ويتم توفير وظائف مماثلة لجافا سكريبت وPHP وRuby وGo وبرمجة التطبيقات.

على سبيل المثال، توضّح علامات التبويب أدناه كيفية استدعاء الدوال المعيارية لإنشاء الموارد لإنشاء مورد playlist. وتجدر الإشارة إلى أنّ الوظائف النموذجية لا تحتاج إلى معرفة نوع المورد الذي يتم إنشاؤه.

جافا سكريبت
function createResource(properties) {
  var resource = {};
  var normalizedProps = properties;
  for (var p in properties) {
    var value = properties[p];
    if (p && p.substr(-2, 2) == '[]') {
      var adjustedName = p.replace('[]', '');
      if (value) {
        normalizedProps[adjustedName] = value.split(',');
      }
      delete normalizedProps[p];
    }
  }
  for (var p in normalizedProps) {
    // Leave properties that don't have values out of inserted resource.
    if (normalizedProps.hasOwnProperty(p) && normalizedProps[p]) {
      var propArray = p.split('.');
      var ref = resource;
      for (var pa = 0; pa < propArray.length; pa++) {
        var key = propArray[pa];
        if (pa == propArray.length - 1) {
          ref[key] = normalizedProps[p];
        } else {
          ref = ref[key] = ref[key] || {};
        }
      }
    };
  }
  return resource;
}
var resource = createResource({
    'snippet.title': 'Sample playlist ',
    'snippet.description': 'This is a sample playlist description.',
    'snippet.tags[]': 'JavaScript code, interactive',
    'snippet.defaultLanguage': '',
    'status.privacyStatus': 'private'
}
Python
# Build a resource based on a list of properties given as key-value pairs.
# Leave properties with empty values out of the inserted resource.
def build_resource(properties):
  resource = {}
  for p in properties:
    # Given a key like "snippet.title", split into "snippet" and "title", where
    # "snippet" will be an object and "title" will be a property in that object.
    prop_array = p.split('.')
    ref = resource
    for pa in range(0, len(prop_array)):
      is_array = False
      key = prop_array[pa]
      # Convert a name like "snippet.tags[]" to snippet.tags, but handle
      # the value as an array.
      if key[-2:] == '[]':
        key = key[0:len(key)-2:]
        is_array = True
      if pa == (len(prop_array) - 1):
        # Leave properties without values out of inserted resource.
        if properties[p]:
          if is_array:
            ref[key] = properties[p].split(',')
          else:
            ref[key] = properties[p]
      elif key not in ref:
        # For example, the property is "snippet.title", but the resource does
        # not yet have a "snippet" object. Create the snippet object here.
        # Setting "ref = ref[key]" means that in the next time through the
        # "for pa in range ..." loop, we will be setting a property in the
        # resource's "snippet" object.
        ref[key] = {}
        ref = ref[key]
      else:
        # For example, the property is "snippet.description", and the resource
        # already has a "snippet" object.
        ref = ref[key]
  return resource

resource = build_resource({
    'snippet.title': 'Sample playlist ',
    'snippet.description': 'This is a sample playlist description.',
    'snippet.tags[]': 'Python code, interactive',
    'snippet.defaultLanguage': '',
    'status.privacyStatus': 'private'}
PHP
// Add a property to the resource.
function addPropertyToResource(&$ref, $property, $value) {
    $keys = explode(".", $property);
    $is_array = false;
    foreach ($keys as $key) {
        // Convert a name like "snippet.tags[]" to "snippet.tags" and
        // set a boolean variable to handle the value like an array.
        if (substr($key, -2) == "[]") {
            $key = substr($key, 0, -2);
            $is_array = true;
        }
        $ref = &$ref[$key];
    }

    // Set the property value. Make sure array values are handled properly.
    if ($is_array && $value) {
        $ref = $value;
        $ref = explode(",", $value);
    } elseif ($is_array) {
        $ref = array();
    } else {
        $ref = $value;
    }
}

// Build a resource based on a list of properties given as key-value pairs.
function createResource($properties) {
    $resource = array();
    foreach ($properties as $prop => $value) {
        if ($value) {
            addPropertyToResource($resource, $prop, $value);
        }
    }
    return $resource;
}

$propertyObject = createResource(array(
    'snippet.title' => 'Sample playlist ',
    'snippet.description' => 'This is a sample playlist description.',
    'snippet.tags[]' => 'Python code, interactive',
    'snippet.defaultLanguage' => '',
    'status.privacyStatus' => 'private'));
روبية
# Build a resource based on a list of properties given as key-value pairs.
def create_resource(properties)
  resource = {}
  properties.each do |prop, value|
    ref = resource
    prop_array = prop.to_s.split(".")
    for p in 0..(prop_array.size - 1)
      is_array = false
      key = prop_array[p]
      if key[-2,2] == "[]"
        key = key[0...-2]
        is_array = true
      end
      if p == (prop_array.size - 1)
        if is_array
          if value == ""
            ref[key.to_sym] = []
          else
            ref[key.to_sym] = value.split(",")
          end
        elsif value != ""
          ref[key.to_sym] = value
        end
      elsif ref.include?(key.to_sym)
        ref = ref[key.to_sym]
      else
        ref[key.to_sym] = {}
        ref = ref[key.to_sym]
      end
    end
  end
  return resource
end

resource = create_resource({
    'snippet.title': 'Sample playlist ',
    'snippet.description': 'This is a sample playlist description.',
    'snippet.tags[]': 'Ruby code, interactive',
    'snippet.default_language': '',
    'status.privacy_status': 'private'})
برمجة تطبيقات Google
// Build an object from an object containing properties as key-value pairs
function createResource(properties) {
  var res = {};
  var normalizedProps = {};
  for (var p in properties) {
    var value = properties[p];
    if (p.substr(-2, 2) == '[]' && value) {
      var adjustedName = p.replace('[]', '');
      normalizedProps[adjustedName] = value.split(',');
    } else {
      normalizedProps[p] = value;
    }
  }
  for (var p in normalizedProps) {
    if (normalizedProps.hasOwnProperty(p) && normalizedProps[p]) {
      var propArray = p.split('.');
      var ref = res;
      for (var pa = 0; pa < propArray.length; pa++) {
        var key = propArray[pa];
        if (pa == propArray.length - 1) {
          ref[key] = normalizedProps[p];
        } else {
          ref = ref[key] = ref[key] || {};
        }
      }
    };
  }
  return res;
}

var resource = createResource({
    'snippet.title': 'Sample playlist ',
    'snippet.description': 'This is a sample playlist description.',
    'snippet.tags[]': 'Apps Script code, interactive',
    'snippet.defaultLanguage': '',
    'status.privacyStatus': 'private'
});
انتقال
func addPropertyToResource(ref map[string]interface{}, keys []string, value string, count int) map[string]interface{} {
        for k := count; k < (len(keys) - 1); k++ {
                switch val := ref[keys[k]].(type) {
                case map[string]interface{}:
                        ref[keys[k]] = addPropertyToResource(val, keys, value, (k + 1))
                case nil:
                        next := make(map[string]interface{})
                        ref[keys[k]] = addPropertyToResource(next, keys, value, (k + 1))
                }
        }
        // Only include properties that have values.
        if (count == len(keys) - 1 && value != "") {
                valueKey := keys[len(keys)-1]
                if valueKey[len(valueKey)-2:] == "[]" {
                        ref[valueKey[0:len(valueKey)-2]] = strings.Split(value, ",")
                } else if len(valueKey) > 4 && valueKey[len(valueKey)-4:] == "|int" {
                        ref[valueKey[0:len(valueKey)-4]], _ = strconv.Atoi(value)
                } else if value == "true" {
                        ref[valueKey] = true
                } else if value == "false" {
                        ref[valueKey] = false
                } else {
                        ref[valueKey] = value
                }
        }
        return ref
}

func createResource(properties map[string]string) string {
        resource := make(map[string]interface{})
        for key, value := range properties {
                keys := strings.Split(key, ".")
                ref := addPropertyToResource(resource, keys, value, 0)
                resource = ref
        }
        propJson, err := json.Marshal(resource)
        if err != nil {
               log.Fatal("cannot encode to JSON ", err)
        }
        return string(propJson)
}

func main() {
        properties := (map[string]string{
                 "snippet.title": "Sample playlist ",
                 "snippet.description": "This is a sample playlist description.",
                 "snippet.tags[]": "Go code, interactive",
                 "snippet.defaultLanguage": "",
                 "status.privacyStatus": "private",
        })
        res := createResource(properties)

تحميل الموارد الحالية

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