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

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

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

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

المحتويات

محتويات هذا الدرس:

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

نظرة خاطفة

درس آخر من سلسلة دروس التعامل مع خدمات تقصير العناوين برمجيا. درس اليوم يتكلم عن خدمة 1click.at وكيفية برمجتها.

مقدمة

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

عند اطلاعك على موقع الخدمة http://1click.at ستجد أنه ليس هناك أسهل من هذه الخدمة للتعامل معها. ولكن للأسف، الرابط القصير الناتج باستخدام هذه الخدمة يصل إلى 24 حرف مما يجعله طويل جدا بالنسبة للخدمات الأخرى.

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

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

هذه الدالة هي http://1click.at/api.php وهي دالة بسيطة جدا تأخذ 3 مدخلات وهي:

1. action:
   حتى الآن، فهذا المدخل يأخذ قيمة واحدة فقط وهي shorturl لإجراء عملية تقصير للرابط. ربما نجد العديد من الأوامر الأخرى مستقبلا.
2. url:
   العنوان الذي تريد تقصيره (طبعا مع ترميزه.)
3. format:
   نوع القيمة المرتجعة. يمكن أن تكون: 1) simple 2) xml 3) json.

كما تعرف، فإن اهتمامنا يكون بالقيمة النصية البسيطة (simple) أو بقيمة الـ XML، وهذا لأنهما مدعومين بشكل جيد من بيئة الدوت نت ولا حاجة لأي مكونات خارجية. لاحظ أنه في حالة استخدامك للنوع XML فإن الناتج يكون كالتالي في حالة نجاح العملية وكون الرابط الطويل لم يتم تقصيره قبل ذلك:

    
        GFbA1zL
        http://WithDotNet.net
        2010-12-17 20:14:04
        0.0.0.0
    
    success
    http://WithDotNet.net added to database
    http://1click.at/GFbA1zL
    200

أما في حالة كود الرابط الطويل تم تقصيره قبل ذلك، فإن الناتج يكون كالتالي:

    fail
    <code>error:url</code>
    http://WithDotNet.net already exists in database
    http://1click.at/GFbA1zL
    200

في كل الأحوال فإنك يمكنك قراءة العنصر shorturl مباشرة.

الآن، نقوم بتجربة هذه الدالة. إذا أردنا مثلا تقصير العنوان http://www.WithDotNet.net فإننا نقوم بالذهاب إلى المتصفح وكتابة عنوان الدالة بمدخلاتها في خانة العنوان، فنكتب مثلا: http://1click.at/api.php?action=shorturl&url=http://WithDotNet.net&format=xml (أو مع تبديل xml بـ simple)، فتقوم الدالة بتنفيذ الأمر وإرجاع الرابط القصير (في حالتنا هذه: http://1click.at/GFbA1zL).

والآن، لنقوم بتطبيق هذه الدالة برمجيا. الدالة الآتية تأخذ العنوان المراد تقصيره وتقوم بالنداء على دالة خدمة 1click.at لتطبيق العملية، ثم تقوم بإرجاع العنوان القصير:

// C#

string Shorten(string url, bool xml)
{
    url = Uri.EscapeUriString(url);
    string reqUri =
String.Format("http://1click.at/api.php?action=shorturl&url={0}&format={1}",
        url, xml ? "xml" : "simple");

    HttpWebRequest req = (HttpWebRequest)WebRequest.Create(reqUri);
    req.Timeout = 10000; // 10 seconds

    // if the function fails and format==txt throws an exception
    Stream stm = req.GetResponse().GetResponseStream();

    if (xml)
    {
        XmlDocument doc = new XmlDocument();
        doc.Load(stm);

        // error checking for xml
        if (doc["result"]["statusCode"].InnerText != "200")
            throw new WebException(doc["result"]["statusCode"].InnerText);

        return doc["result"]["shorturl"].InnerText;
    }
    else // Text
        using (StreamReader reader = new StreamReader(stm))
            return reader.ReadLine();
}

' VB.NET

Private Function Shorten(url As String, xml As Boolean) As String
	url = Uri.EscapeUriString(url)
	Dim reqUri As String = "http://1click.at/api.php?action=shorturl&url={0}&format={1}"
	If (xml) Then
		reqUri = String.Format(reqUri, url, "xml")
	Else
		reqUri = String.Format(reqUri, url, "simple")
	End If

	Dim req As HttpWebRequest = DirectCast(WebRequest.Create(reqUri), HttpWebRequest)
	req.Timeout = 5000
	Dim stm As Stream = req.GetResponse().GetResponseStream()

	If xml Then
		Dim doc As New XmlDocument()
		doc.Load(stm)

		' error checking for xml
		If doc("result")("statusCode").InnerText  "200" Then
			Throw New WebException(doc("result")("statusCode").InnerText)
		End If

		Return doc("result")("shorturl").InnerText
	Else
		' Simple
		Using reader As New StreamReader(stm)
			Return reader.ReadLine()
		End Using
	End If
End Function

لاحظ أننا نحتاج إلى عمل ترميز Encoding للعنوان المراد تقصيره قبل إضافته كمدخلات وذلك لإزالة الأحرف التي يمكن أن تسبب إشكال بالنسبة للعنوان مثل المسافات وعلامات الاستفهام ونحوها. ولعمل هذا قمنا بالاستفاد من الدالة System.Net.Uri.EscapeUriString().

لاحظ أيضا أنه يمكن أن يحدث خطأ في العملية ولذلك نقوم بالتأكد من حدوث الخطأ System.Net.WebException وذلك لتفادي توقف البرنامج أثناء العمل.

ماذا بعد

هذا ويمكنكم القراءة أكثر في هذه السلسلة هنا.