البدء

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

الإعداد

إليك بعض خطوات الإعداد التي يجب إكمالها قبل استخدام هذه المكتبة:

1. إذا لم يكن لديك حساب على Google، يمكنك الاشتراك.
2. إذا لم يسبق لك إنشاء مشروع Google API Console، يمكنك الاطّلاع على صفحة إدارة المشاريع وإنشاء مشروع في وحدة تحكّم Google API.
3. ثبِّت حزمة NuGet التي تريد استخدامها.

المصادقة والتفويض

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

1- الوصول إلى واجهة برمجة التطبيقات البسيطة (مفاتيح واجهة برمجة التطبيقات)

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

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

2. الدخول إلى واجهة برمجة التطبيقات المعتمدة (OAuth 2.0)

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

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

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

معرِّف العميل وسر العميل: تحدِّد هذه السلاسل تطبيقك بشكل فريد، وتُستخدم للحصول على الرموز المميّزة. يتم إنشاؤها لمشروعك في وحدة تحكم واجهة برمجة التطبيقات. هناك ثلاثة أنواع من معرِّفات العملاء، لذا تأكَّد من الحصول على النوع الصحيح لتطبيقك:

• معرّفات عملاء تطبيق الويب
• معرِّفات عملاء التطبيقات المثبتة
• معرّفات عملاء حساب الخدمة

أمثلة

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

مثال على Simple API

يستخدم هذا المثال عملية بسيطة للوصول إلى واجهة برمجة التطبيقات لتطبيق سطر الأوامر. واستدعاء واجهة برمجة التطبيقات Google Discovery API لإدراج جميع واجهات Google APIs.

الإعداد على سبيل المثال

الحصول على مفتاح Simple API: للعثور على مفتاح واجهة برمجة التطبيقات لتطبيقك، نفِّذ ما يلي:

1. افتح صفحة بيانات الاعتماد في وحدة تحكّم واجهة برمجة التطبيقات.
2. وتتوافق واجهة برمجة التطبيقات هذه مع نوعَين من بيانات الاعتماد. أنشئ بيانات الاعتماد المناسبة لمشروعك:

   • OAuth 2.0: عندما يطلب التطبيق بيانات المستخدم الخاصة، يجب أن يرسل رمز OAuth 2.0 المميز إلى جانب الطلب. يرسل تطبيقك أولاً معرِّف عميل، وربما سرًّا عميلاً للحصول على رمز مميز. يمكنك إنشاء بيانات اعتماد OAuth 2.0 لتطبيقات الويب أو حسابات الخدمة أو التطبيقات المثبّتة.

     لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OAuth 2.0.

   • مفاتيح واجهة برمجة التطبيقات: يجب أن يرسل الطلب الذي لا يوفّر رمز OAuth 2.0 المميز مفتاحًا لواجهة برمجة التطبيقات. يحدد المفتاح مشروعك، ويتيح الوصول إلى واجهة برمجة التطبيقات، والحصة، والتقارير.

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

للحفاظ على أمان مفاتيح واجهة برمجة التطبيقات، اتّبِع أفضل الممارسات لاستخدام مفاتيح واجهة برمجة التطبيقات بشكل آمن.

رمز مثلاً

using System;
using System.Threading.Tasks;

using Google.Apis.Discovery.v1;
using Google.Apis.Discovery.v1.Data;
using Google.Apis.Services;

namespace Discovery.ListAPIs
{
    /// <summary>
    /// This example uses the discovery API to list all APIs in the discovery repository.
    /// https://developers.google.com/discovery/v1/using.
    /// <summary>
    class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("Discovery API Sample");
            Console.WriteLine("====================");
            try
            {
                new Program().Run().Wait();
            }
            catch (AggregateException ex)
            {
                foreach (var e in ex.InnerExceptions)
                {
                    Console.WriteLine("ERROR: " + e.Message);
                }
            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }

        private async Task Run()
        {
            // Create the service.
            var service = new DiscoveryService(new BaseClientService.Initializer
                {
                    ApplicationName = "Discovery Sample",
                    ApiKey="[YOUR_API_KEY_HERE]",
                });

            // Run the request.
            Console.WriteLine("Executing a list request...");
            var result = await service.Apis.List().ExecuteAsync();

            // Display the results.
            if (result.Items != null)
            {
                foreach (DirectoryList.ItemsData api in result.Items)
                {
                    Console.WriteLine(api.Id + " - " + api.Title);
                }
            }
        }
    }
}

نصائح حول استخدام مفاتيح واجهة برمجة التطبيقات:

• لاستخدام خدمة معيّنة، يجب إضافة مرجع إليها. على سبيل المثال، إذا كنت تريد استخدام Tasks API، عليك تثبيت حزمة NuGet Google.Apis.Tasks.v1.
• لإنشاء مثيل لإحدى الخدمات، كل ما عليك هو الاتصال بالمُنشئ الخاص بها. مثلاً: new TasksService(new BaseClientService.Initializer {...});"
• تتوفر جميع طرق الخدمة على الموارد الفردية في عنصر الخدمة نفسه. تتضمن خدمة "اقتراحات" مورد Apis، الذي يحتوي على طريقة List. وعند استدعاء service.Apis.List(..)، يتم عرض عنصر طلب يستهدف هذه الطريقة.
  لتنفيذ طلب، يجب استدعاء الطريقة Execute() أو ExecuteAsyc() في أحد الطلبات.
• ويمكنك ضبط مفتاح واجهة برمجة التطبيقات باستخدام السمة ApiKey على النسخة الافتراضية BaseClientService.Initializer.

العثور على معلومات عن واجهات برمجة التطبيقات

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

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