الاستفادة من خدمات تقصير العناوين برمجيا – خدمة X.co

This article is available in English too, check it out here.

يمكنكم قراءة المزيد عن خدمات تقصير العناوين هنا.

المثال- Elsheimy.Samples.ShortenSvcs.zip

المحتويات

محتويات هذا الموضوع:

  • المحتويات
  • نظرة خاطفة
  • مقدمة
  • الواجهة البرمجية
  • خدمات الويب
    • خدمة التقصير
    • خدمة التقارير
  • خدمات REST
    • خدمة التقصير
    • خدمة التقارير
  • المثال
  • ماذا بعد

نظرة خاطفة

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

اليوم نتكلم عن المميزات التي تدعمها خدمة X.co بالإضافة إلى كيفية برمجتها في بيئة الدوت نت والاستفادة من الواجهة البرمجية التي تدعمها.

مقدمة

اليوم نتكلم عن خدمة أخرى من خدمات تقصير العناوين المتميزة والمتطورة جدا وهي خدمة X.co المقدمة من مؤسسة Go Daddy الأشهر على الإطلاق في مجال النطاقات والاستضافات.

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

الواجهة البرمجية

من أحد أهم مميزات خدمة X.co هي أنها توفر لك واجهة برمجية متطورة جدا، وهذه الواجهة متوفرة كنوعين:

  1. خدمات WCF
  2. خدمات REST (مثل الواجهات البرمجية لخدمات تقصير العناوين الأخرى.)

كما تعلم فإن خدمات WCF مدعومة بشكل كبير جدا في بيئة الدوت نت وهذا سوف يمثل لك سهولة وسرعة كبيرة في التعامل مع هذه الخدمة وفي كتابة الأكواد اللازمة.

ماذا إذا كان مشروعك يعتمد على الإصدار الثاني من الدوت نت .NET 2.0؟ إذا فخدمات WCF ليست مدعومة؟ بالطبع لا، فرغم أن خدمات WCF هي تقنية جديدة ظهرت في الإصدار الثالث من بيئة الدوت نت .NET 3.0، فإن خدمات WCF تدعم أيضا طرق للاتصال مع الإصدار الثاني .NET 2.0 حيث أنه يتم الوصول إليها كخدمات ويب Web Services عادية جدا وليس هناك أدنى فرق في طرق الوصول إليها أو حتى في كتابة الكود (اللهم إلا فروق طفيفة جدا في تعريف الدوال) سواء كنت تستخدم .NET 2.0 أو إصدار أعلى (بالطبع لا تفكر أبدا في استخدام إصدار سابق لـ .NET 2.0)

سنبدأ أولا بشرح خدمات الويب التي توفرها خدمة X.co ثم سوف نتعرض بعد ذلك لدوال REST التي توفرها. ولكن قبل ذلك، تحتاج إلى الحصول على المفتاح البرمجي API Key كي يمكنك استخدام الخدمة برمجيا، ولكي تستطيع الحصول على هذا المفتاح ستحتاج أولا إلى إنشاء حساب في Go Daddy إن لم يكن لديك واحد، ويتم ذلك عن طريق الذهاب إلى http://www.godaddy.com والضغط على Create Account في أعلى الصفحة (انظر شكل 1) ثم قم بملء هذه العريضة من البيانات المطلوبة واستكمال عملية التسجيل.

شكل 1 - صفحة تسجيل Go Daddy

شكل 1 - صفحة تسجيل Go Daddy

بعد ذلك، قم بالذهاب إلى http://x.co والدخول ببيانات تسجيلك، ومن ثم اختر Settings لعرض المفتاح البرمجي الخاص بك. لاحظ شكل 2.

شكل 2 - المفتاح البرمجي لـ X.co

شكل 2 - المفتاح البرمجي لـ X.co

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

خدمات الويب

توفر لك خدمة X.co خدمتان ويب WCF (أو Web Services) تستطيع استخدامهما ببساطة من خلال برنامجك.:

  1. خدمة التقصير Squeeze http://api.x.co/Squeeze.svc:
    وتحوي فقط أمر واحد لتقصير العناوين الطويلة وهو SqueezeUrl() (الأوامر الأخرى إما ملغية أو خاصة بالاستخدام الداخلي لـ Go Daddy.)
  2. خدمة التحليلات والتقارير Analytics and Reports http://api.x.co/Reporting.svc:
    وتحوي العديد من الأوامر الخاصة بالحصول على التحليلات للروابط المقصرة مثل الحصول على عدد الضغطات Clicks والصفحات المشيرة إلى الرابط القصير Referrers وأيضا الأماكن (مثلا مصر) التي تم استخدام الرابط منها Locations.

أيا كانت الخدمة التي ستستخدمها فسوف تحتاج إلى إضافة ملفات الاتصال إلى مشروعك. وبما أنك بالطبع لا تفضل كتابتها يدويا، فيمكنك استخدام أحد طريقتين. الأولى باستخدام نافذة إضافة مراجع الويب في الفيجوال ستوديو والتي يمكنك مشاهدتها بالضغط بزر الفأرة الأيمن على Web References الموجودة تحت مشروعك في متصفح المشاريع Solution Explorer، لاحظ شكل 3.

شكل 3 - متصفح المشاريع - إضافة مرجع ويب

شكل 3 - متصفح المشاريع - إضافة مرجع ويب

لتظهر لك شاشة إضافة مراجع الويب (خدمات الويب) والتي تختلف قليلا باختلاف إصدار الدوت نت الذي تستخدمه (راجع شكل 4 وشكل 5.) في كل الأحوال قم بكتابة عنوان الخدمة في حقل العنوان واضغط على زر Go لكي تبدأ بعملية المراجعة للخدمة التي بمجرد انتهائها تقوم بتحديد اسم مناسب للخدمة (والذي سيستخدم كاسم للنطاق Namespace لملفات الكود للخدمة) والضغط على زر Add Reference لكي يتم إضافة ملفات الخدمة إلى مشروعك. لاحظ أننا في مثالنا هذا استخدمنا الاسم xcoapi للخدمة الأولى Squeeze والاسم xcpapirpt للخدمة الثانية Reporting.

شكل 4 - نافذة إضافة مرجع ويب - دوت نت 2.0

شكل 4 - نافذة إضافة مرجع ويب - دوت نت 3.5+

شكل 5 - نافذة إضافة مرجع ويب - دوت نت 2.0

شكل 5 - نافذة إضافة مرجع ويب - دوت نت 2.0

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

svcutil.exe http://api.x.co/Squeeze.svc?wsdl /language=C#
svcutil.exe http://api.x.co/Squeeze.svc?wsdl /language=VB

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

خدمة التقصير

الخدمة الأولى معنا وهي كما تعلم خدمة التقصير Squeeze وهي لها العنوان http://api.x.co/Squeeze.svc. أولا يجب عليك إضافة الخدمة إلى مشروعك (انظر القسم السابق.) هذه الخدمة لا نحتاج منها سوى دالة واحدة وهي دالة Shorten() والتي ببساطة تأخذ فقط مدخلين:

  • url:
    العنوان المراد تقصيره.
  • apiKey:
    المفتاح البرمجي (انظر القسم الواجهة البرمجية من الموضوع.)

أما الدوال الأخرى فتتراوح ما بين كونها ملغية أو كونها خاصة بالاستخدام الداخلي لـ Go Daddy.

الكود التالي يوضح ببساطة كيفية تعاملنا مع دالة Shorten() (وأيضا جميع الدوال الأخرى):

// C#
string Shorten(string url, string apiKey)
{
    using (xcoapi.Squeeze sq = new xcoapi.Squeeze())
    {
        return sq.Shorten(url, apiKey);
    }
}

لاحظ استخدامنا لجملة using (في C# مقابلها أمر Dispose() في VB.NET) لضمان الاستغلال الأمثل للموارد والمحافظة على أداء البرنامج والكود.

في الكود السابق تقوم الدالة بإرجاع الرابط القصير (والذي حتى الآن لا يتعدى 16 حرفا) مثل http://x.co/8Gg8.

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

الخدمة الأخرى معنا والتي توفرها X.co وهي خدمة التقارير والتي لها العنوان http://api.x.co/Reporting.svc والتي توفر لك العديد من الدوال التي يمكنك من خلال معرفة جميع التقارير والتحليلات الخاصة بعناوينك القصيرة. وتنحصر هذه التحيلات في ثلاثة فئات:

  • عدد الضغطات Clicks (عدد استخدامات الرابط القصير)
  • الصفحات المشيرة إلى هذا الرابط Referrer Sites (أي التي تم استخدام الرابط من خلالها)
  • الأماكن Locations التي تم استخدام الرابط منها (مثلا المدينة، المنطقة، والدولة)

وتدعم هذه الخدمة 5 دوال:

  • GetTotalMapClick():
    للحصول على العدد الكلي للضغطات.
  • GetMapClicksByDates():
    للحصول على عدد الضغطات في عدد أيام معين.
  • GetMapClicksByHour():
    للحصول على عدد الضغطات لهذا اليوم.
  • GetMapReferrersByDates():
    للحصول على الصفحات المشيرة في أيام معينة وعدد الضغطات لكل صفحة.
  • GetMapLocationsByDates():
    للحصول على الأماكن (الجغرافية) التي تمت زيارة الرابط منها في فترة زمنية معينة.

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

  • apiKey:
    المفتاح البرمجي.
  • encoded:
    الكود الخاص بالرابط القصير بدون عنوان الموقع، مثلا 8Gg8 في http://x.co/8Gg8 (لاحظ أنه يجب المطابقة في حالة  مطابق لحالة الأحرف.)

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

بطريقة مشابهة تعمل الدوال الثلاثة الأخرى GetMapClicksByDates()،GetMapReferrersByDates()، و GetMapLocationsByDates()، فهذه الدوال تأخذ مدخلين إضافيين الأول يمثل تاريخ البدأ والثاني يمثل تاريخ الانتهاء. وفكرة هذه الدوال هي أنها ترجع بيانات بناءا على مدة زمنية معينة وتكون البيانات في صيغة مصفوفات تحوي عناصر كل منها تمثل يوم معين والبيانات الخاصة بهذا اليوم.

بعد إضافتك لخدمة التقارير Reporting إلى مشروعك، يمكنك الآن البدأ في كتابة الأكواد. الكود التالي يقوم باسترجاع العدد الكلي للضغطات لرابط قصير معين:

// C#
int GetTotalClicks(string shortCode, string apiKey)
{
    using (xcoapirpt.Reporting rpt = new xcoapirpt.Reporting())
    {
        int totalClicks;
        bool succeeded;
        rep.GetTotalMapClick(apiKey, shortCode, out totalClicks, out succeeded);
        return succeeded ? totalClicks : -1;
    }
}

لاحظ الفرق بين الكود السابق والذي يستخدم في الإصدار الثاني من الدوت نت .NET 2.0 ونفس الكود الذي يستخدم مع الإصدارات الأحدث:

// C#
int GetTotalClicks(string shortCode, string apiKey)
{
    using (xcoapirpt.ReportingClient rpt = new xcoapirpt.ReportingClient())
    {
        return rep.GetTotalMapClick(apiKey, shortCode);
    }
}

لا نقصد الفرق بين اسم الكلاس المستخدمة الخاصة بالخدمة حيث أن هذا الاسم راجع إلى اختيارك، ولكننا نقصد أنه في حالة استخدامك للخدمة كـ Web Service (في الإصدار الثاني .NET 2.0) فإن الدوال لا تقوم بإرجاع قيمة باستخدام جملة return بل تكون القيمة المرتجعة موجودة كمدخل للدالة قابل للتعديل.

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

// C#
xcoapirpt.ReferrerEventInfo[] GetReferrers
    (string shortCode, string apiKey, out int totalClicks)
{
    using (xcoapirpt.Reporting rep = new xcoapirpt.Reporting())
    {
        xcoapirpt.ReferrerEventInfo[] results =
            rep.GetMapReferrersByDates(apiKey, shortCode,
                DateTime.Now - new TimeSpan(7, 0, 0, 0, 0), true, DateTime.Now, true);
        totalClicks = 0;
        foreach (xcoapirpt.ReferrerEventInfo r in results)
            totalClicks += r.TotalSpecified ? r.Total : 0;
        return results;
    }
}

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

بالطبع فكل دالة من الدوال الأربع ترجع مصفوفة من عناصر من نوع معين خاصة بها. فالدالة السابقة تقوم بإرجاع مصفوفة من نوع ReferrerEventInfo والتي تحوي بيانات كل صفحة (عنوان الصفحة وعدد الضغطات فيها.)

خدمات REST

إذا كنت لا تريد استخدام خدمات الويب السابقة فيمكنك أيضا استخدام خدمات REST التي توفرها x.co وهي عبارة عن مجموعة من دوال أو نقاط وصول موجودة على الويب لها صيغ معينة للبيانات التي ترجعها بعضها نص بسيط Plain Text، وبعضها الآخر XML، والبعض JSON (ليس غريبا عليك فخدمات WCF السابق ذكرها توفر لك نقاط وصول إليها بصيغة REST.)

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

خدمة التقصير

أيضا فخدمة التقصير في REST لها نفس العنوان ألا وهو http://api.x.co/Squeeze.svc. توفر لك هذه الخدمة دالتين الأولى تقوم بإرجاع البيانات بصيغة JSON أما الثانية فترجعها بصيغة نص بسيط Plain Text ولهذا فسوف يكون تركيزنا على الثانية والتي لها الصيغة التالية:

http://api.x.co/Squeeze.svc/text/{apiKey}?url={url}

أما الآن، فالكود التالي يقوم بالنداء على دالتنا دالة التقصير الخاصة بخدمة الـ REST، هذا الكود لا يختلف في نتائجه عن الكود الخاص بخدمة WCF:

// C#
string Shorten(string url, string apiKey)
{
    WebRequest req = HttpWebRequest.Create(
        string.Format("http://api.x.co/Squeeze.svc/text/{0}?url={1}",
        apiKey, url));
    req.Timeout = 10000; // 10 seconds
    string shortUrl;
    System.IO.Stream stm;
    stm = req.GetResponse().GetResponseStream();
    using (System.IO.StreamReader rdr = new System.IO.StreamReader(stm))
    {
        return rdr.ReadToEnd();
    }
}

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

أيضا فخدمة التقارير لها نفس العنوان وهو http://api.x.co/Squeeze.svc. وهذه الخدمة بها تدعم نفس الدوال السابقة التي تعرضنا لها في WCF ولكن لسوء الحظ فهذه الدوال كلها عدا واحدة تدعم صيغة واحدة فقط وهي JSON، ولأن الدوت نت لا يدعم JSON بشكل مباشر بل يجب عليك استخدام مكاتب خارجية (أشهرها Json.NET) فإننا لن نتعرض لشرح هذه الدوال، ولكن يتبقى لنا دالة واحدة تقوم بإرجاع نصية وهي دالة Total Clicks والتي تقوم بإرجاع العدد الكلي لاستخدامات هذا الرابط القصير. هذه الدالة يمكننا كتابة كود استخدامها كالتالي:

// C#
int GetTotalClicks(string shortCode, string apiKey)
{
    WebRequest req = HttpWebRequest.Create(
        string.Format("http://x.co/Reporting.svc/map/{0}/{1}/total",
        apiKey, shortCode));
    req.Timeout = 10000; // 10 seconds
    System.IO.Stream stm;
    stm = req.GetResponse().GetResponseStream();
    using (System.IO.StreamReader rdr = new System.IO.StreamReader(stm))
    {
        return int.Parse(rdr.ReadToEnd());
    }
}

لاحظ أن المطلوب هو العنوان القصير بدون اسم النطاق أي بدون http://x.co/.

المثال

يمكنكم تحميل المثال الكامل عن برمجة خدمات تقصير العناوين هنا.

ماذا بعد

يمكنكم قراءة المزيد عن خدمات تقصير العناوين هنا.

مواضيع مشابهة:

اخترنا لك:

أحدث المواضيع:

هل أعجبتك؟ شارك بها...