البدء

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

الإعداد

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

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

المصادقة والترخيص

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

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

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

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

2. الوصول المصرّح به إلى واجهة برمجة التطبيقات (OAuth 2.0)

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

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

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

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

أمثلة

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

مثال بسيط لواجهة برمجة التطبيقات

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

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

احصل على مفتاح واجهة برمجة التطبيقات البسيطة. للبحث عن مفتاح واجهة برمجة التطبيقات لتطبيقك، يمكنك إجراء ما يلي:

  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 {...});".
  • تتوفّر جميع طرق الخدمة على موارد فردية في كائن الخدمة نفسه. تحتوي خدمة Discovery على مورد Apis، والذي يحتوي على الطريقة List. عند استدعاء service.Apis.List(..)، يتم عرض عنصر طلب يستهدف هذه الطريقة.
    لتنفيذ طلب، يمكنك استدعاء الإجراء Execute() أو ExecuteAsyc() في الطلب.
  • اضبط مفتاح واجهة برمجة التطبيقات باستخدام السمة ApiKey على المثيل BaseClientService.Initializer.

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

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

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