الخطوات الأولى

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

ضبط إعدادات الجهاز

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

1. إذا لم يكن لديك حساب Google بالفعل، الاشتراك
2. إذا لم يسبق لك إنشاء مشروع في وحدة تحكم واجهة برمجة تطبيقات Google، فاقرأ صفحة "إدارة المشاريع" وإنشاء مشروع في وحدة التحكم في واجهة 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.

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

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

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

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

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