الصفحة الرئيسية>المتعلقة بالبرمجة>VB.NET
تنزيل

Verifalia RESTful API - .NET SDK ومكتبة المساعدة

توفر Verifalia واجهة برمجة تطبيقات بسيطة تعتمد على HTTPS للتحقق من صحة عناوين البريد الإلكتروني في الوقت الفعلي والتحقق مما إذا كانت قابلة للتسليم أم لا؛ تتكامل مكتبة SDK هذه مع Verifalia وتسمح بالتحقق من عناوين البريد الإلكتروني ضمن الأنظمة الأساسية التالية:

  • .NET 5.0 والإصدارات الأحدث، بما في ذلك .NET 8.0
  • .NET Core 1.0 (والإصدارات الأحدث)
  • .NET Framework 4.5 (والإصدارات الأحدث)
  • .NET Standard 1.3 (والإصدارات الأحدث)
    • مونو 4.6+
    • زامارين.iOS 10.0+
    • زامارين.ماك 3.0+
    • زامارين.أندرويد 7.0+
    • منصة ويندوز العالمية 10.0+

لمعرفة المزيد حول Verifalia، يرجى زيارة https://verifalia.com

جدول المحتويات

  • إضافة دعم Verifalia REST API إلى حل .NET الخاص بك
    • مع Visual Studio IDE
    • التحميل اليدوي والتجميع
    • المصادقة
      • المصادقة عبر الرمز المميز لحاملها
      • المصادقة عبر شهادة العميل X.509 (مصادقة TLS المتبادلة)
  • التحقق من صحة عناوين البريد الإلكتروني
    • كيفية التحقق من صحة عنوان البريد الإلكتروني
    • كيفية التحقق من صحة قائمة عناوين البريد الإلكتروني
    • كيفية استيراد وتقديم ملف للتحقق من صحته
    • خيارات المعالجة
      • مستوى الجودة
      • وضع إلغاء البيانات المكررة
      • الاحتفاظ بالبيانات
    • خيارات الانتظار
      • تجنب الانتظار
      • تتبع التقدم
    • عمليات الاسترجاعات الانتهاء
    • إسترجاع الوظائف
    • تصدير نتائج التحقق من البريد الإلكتروني بتنسيقات إخراج مختلفة
    • لا تنس التنظيف عند الانتهاء
    • التكرار على وظائف التحقق من صحة البريد الإلكتروني الخاص بك
      • تصفية وظائف التحقق من صحة البريد الإلكتروني
  • إدارة الاعتمادات
    • الحصول على رصيد الاعتمادات
    • استرجاع إحصائيات استخدام الاعتمادات
  • سجل التغيير / ما الجديد

إضافة دعم Verifalia REST API إلى حل .NET الخاص بك

أفضل وأسهل طريقة لإضافة مكتبة SDK للتحقق من البريد الإلكتروني من Verifalia إلى مشروع .NET الخاص بك هي استخدام مدير الحزم NuGet.

مع Visual Studio IDE

من داخل Visual Studio، يمكنك استخدام NuGet GUI للبحث عن حزمة Verifalia NuGet وتثبيتها. أو، كاختصار، اكتب الأمر التالي في وحدة تحكم إدارة الحزم: 

 Install-Package Verifalia

التحميل اليدوي والتجميع

كطريقة بديلة لإضافة Verifalia SDK إلى حل .NET الخاص بك، يمكنك تنزيل مشروع SDK المصدر من github، واستخراجه إلى مجلد من اختيارك وإضافة مرجع من مشروعك الخاص إلى مشروع Verifalia SDK. مشروع SDK هو مشروع C# يمكن الرجوع إليه واستخدامه مع أي لغة .NET أخرى أيضًا، بما في ذلك Visual Basic (VB.NET)، وC++/CLI، وJ#، وIronPython، وIronRuby، وF#، وPowerShell.

تعرف على المزيد على https://verifalia.com

المصادقة

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

تعرف على المزيد حول المصادقة إلى Verifalia API على https://verifalia.com/developers#authentication

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

 using Verifalia . Api ;

var verifalia = new VerifaliaRestClient ( "username" , "password" ) ;

بالإضافة إلى طريقة HTTP Basic Auth، يدعم SDK هذا أيضًا طرقًا مختلفة أخرى للمصادقة على Verifalia API، كما هو موضح في الأقسام التالية.

المصادقة عبر الرمز المميز لحاملها

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

 using Verifalia . Api ;
using Verifalia . Api . Security ;

var verifalia = new VerifaliaRestClient ( new BearerAuthenticationProvider ( "username" , "password" ) ) ;

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

 using Verifalia . Api ;
using Verifalia . Api . Security ;

class MyTotpProvider : ITotpTokenProvider
{
	public Task < string > ProvideTotpTokenAsync ( CancellationToken cancellationToken )
	{
		// Ask the user to type his or her TOTP token

		Console . WriteLine ( "Acquire your TOTP token and type it here:" ) ;
		var totpToken = Console . ReadLine ( ) ;

		return Task . FromResult ( totpToken ) ;
	}
}

// ...

var verifalia = new VerifaliaRestClient ( new BearerAuthenticationProvider ( "username" , "password" , new MyTotpProvider ( ) ) ) ;

المصادقة عبر شهادة العميل X.509 (مصادقة TLS المتبادلة)

تستخدم طريقة المصادقة هذه شهادة عميل X.509 مشفرة للمصادقة مقابل Verifalia API، من خلال بروتوكول TLS. توفر هذه الطريقة، والتي تسمى أيضًا مصادقة TLS المتبادلة (mTLS) أو المصادقة ثنائية الاتجاه، أعلى درجة من الأمان، حيث يتم إرسال مفتاح مشتق من التشفير فقط (وليس بيانات الاعتماد الفعلية) عبر السلك في كل طلب. 

 using Verifalia . Api ;
using Verifalia . Api . Security ;

var verifalia = new VerifaliaRestClient ( new X509Certificate2 ( "mycertificate.pem" ) ) ;

التحقق من صحة عناوين البريد الإلكتروني

يتم تنفيذ كل عملية تتعلق بالتحقق/التحقق من صحة عناوين البريد الإلكتروني من خلال خاصية EmailValidations التي كشف عنها مثيل VerifaliaRestClient الذي قمت بإنشائه أعلاه. الخاصية مليئة بالطرق المفيدة، كل منها بها الكثير من التحميل الزائد: في الفقرات القليلة التالية، سننظر إلى الطرق الأكثر استخدامًا، لذلك يُنصح بشدة باستكشاف المكتبة والنظر إلى تعليمات xmldoc المضمنة للحصول على فرص أخرى.

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

كيفية التحقق من صحة عنوان البريد الإلكتروني

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

ملاحظة: في حالة احتياجك إلى التحقق من قائمة عناوين البريد الإلكتروني، فمن المستحسن إرسالها جميعًا مرة واحدة من خلال إحدى عمليات التحميل الزائد لأسلوب SubmitAsync() المخصصة (راجع الأقسام التالية)، بدلاً من التكرار على مجموعة المصدر وإرسال عناوين واحدا تلو الآخر. لن تكون طريقة الكل في وقت واحد أسرع فحسب، بل ستسمح أيضًا باكتشاف العناصر المكررة ووضع علامة عليها - وهي ميزة غير متوفرة أثناء التحقق من عناوين البريد الإلكتروني واحدًا تلو الآخر.

في المثال التالي، نقوم بالتحقق من عنوان البريد الإلكتروني في هذه المكتبة، باستخدام الخيارات الافتراضية: 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( "[email protected]" ) ;

// At this point the address has been validated: let's print its email validation
// result to the console.

var entry = job . Entries [ 0 ] ;

Console . WriteLine ( $ "Classification: { entry . Classification } (status: { entry . Status } )" ) ;

// Classification: Deliverable (status: Success)

كما قد تتوقع، قد يتضمن كل إدخال تفاصيل إضافية مختلفة حول عنوان البريد الإلكتروني الذي تم التحقق منه:

ملكية وصف
AsciiEmailAddressDomainPart الحصول على جزء المجال من عنوان البريد الإلكتروني، وتحويله إلى ASCII إذا لزم الأمر، مع إزالة التعليقات والمسافات البيضاء القابلة للطي.
Classification قيمة ValidationEntryClassification لهذا الإدخال.
CompletedOn تاريخ اكتمال هذا الإدخال، إذا كان متاحًا.
Custom سلسلة مخصصة واختيارية يتم تمريرها مرة أخرى عند إكمال التحقق من الصحة. لتمرير قيمة مخصصة ذهابًا وإيابًا، استخدم الخاصية Custom لـ ValidationRequestEntry .
DuplicateOf الفهرس الصفري لأول ظهور لعنوان البريد الإلكتروني هذا في Validation الأصلي، في حالة كون Status هذا الإدخال Duplicate ؛ لا تكشف العناصر المكررة أي تفاصيل نتيجة بصرف النظر عن هذه والقيم Custom النهائية.
Index فهرس هذا الإدخال ضمن حاوية Validation الخاصة به؛ تكون هذه الخاصية مفيدة في الغالب في حالة إرجاع واجهة برمجة التطبيقات (API) لعرض تمت تصفيته للعناصر.
InputData يتم التحقق من صحة سلسلة الإدخال.
EmailAddress يحصل على عنوان البريد الإلكتروني، دون أي تعليق نهائي أو مساحة بيضاء قابلة للطي. إرجاع قيمة فارغة إذا كانت بيانات الإدخال ليست عنوان بريد إلكتروني غير صالح من الناحية النحوية.
EmailAddressDomainPart يحصل على جزء المجال من عنوان البريد الإلكتروني، بدون تعليقات ومسافات بيضاء قابلة للطي.
EmailAddressLocalPart يحصل على الجزء المحلي من عنوان البريد الإلكتروني، بدون تعليقات ومسافات بيضاء قابلة للطي.
HasInternationalDomainName إذا كان هذا صحيحًا، فإن عنوان البريد الإلكتروني له اسم نطاق دولي.
HasInternationalMailboxName إذا كان صحيحًا، فإن عنوان البريد الإلكتروني له اسم صندوق بريد دولي.
IsDisposableEmailAddress إذا كان هذا صحيحًا، فإن عنوان البريد الإلكتروني يأتي من موفر عنوان بريد إلكتروني يمكن التخلص منه (DEA). ما هو عنوان البريد الإلكتروني القابل للتصرف؟
IsFreeEmailAddress إذا كان هذا صحيحًا، فإن عنوان البريد الإلكتروني يأتي من مزود عنوان بريد إلكتروني مجاني (مثل gmail، yahoo، outlook / hotmail، ...).
IsRoleAccount إذا كان هذا صحيحًا، فإن الجزء المحلي من عنوان البريد الإلكتروني هو حساب دور معروف.
Status قيمة ValidationEntryStatus لهذا الإدخال.
Suggestions التصحيحات المحتملة لبيانات الإدخال، في حالة تحديد Verifalia للأخطاء المطبعية المحتملة أثناء عملية التحقق.
SyntaxFailureIndex موضع الحرف في عنوان البريد الإلكتروني الذي تسبب في النهاية في فشل التحقق من صحة بناء الجملة.

فيما يلي مثال آخر يوضح بعض تفاصيل النتائج الإضافية المقدمة من Verifalia: 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( "bat[[email protected]" ) ;

var entry = job . Entries [ 0 ] ;

Console . WriteLine ( $ "Classification: { entry . Classification } " ) ;
Console . WriteLine ( $ "Status: { entry . Status } " ) ;
Console . WriteLine ( $ "Syntax failure index: { entry . SyntaxFailureIndex } " ) ;

if ( entry . Suggestions != null )
{
    Console . WriteLine ( "Suggestions:" ) ;

    foreach ( var suggestion in entry . Suggestions )
    {
        Console . WriteLine ( $ "- { suggestion } " ) ;
    }
}

// Classification: Undeliverable
// Status: InvalidCharacterInSequence
// Syntax failure index: 3
// Suggestions:
// - [email protected]

كيفية التحقق من صحة قائمة عناوين البريد الإلكتروني

للتحقق من قائمة عناوين البريد الإلكتروني - بدلاً من عنوان واحد - من الممكن استخدام التحميل الزائد لأسلوب SubmitAsync() الذي يقبل IEnumerable<string> ؛ إذا كانت عناوين البريد الإلكتروني المراد التحقق منها مخزنة في ملف في الأصل، فمن الممكن أيضًا تحميل الملف ببساطة وجعل Verifalia تقوم باستيراده والتحقق منه تلقائيًا - راجع القسم التالي للحصول على التفاصيل.

فيما يلي مثال يوضح كيفية التحقق من المصفوفة باستخدام بعض عناوين البريد الإلكتروني: 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( new [ ] {
        "[email protected]" ,
        "[email protected]" ,
        "[email protected]"
    } ) ;

Console . WriteLine ( $ "Job ID: { job . Overview . Id } " ) ;

foreach ( var entry in job . Entries )
{
    Console . WriteLine ( $ "- { entry . InputData } => { entry . Classification } ( { entry . Status } )" ) ;
}

// Job Id: 290b5146-eeac-4a2b-a9c1-61c7e715f2e9
// - [email protected] => Deliverable (Success)
// - [email protected] => Undeliverable (DomainIsMisconfigured)
// - [email protected] => Deliverable (Success)

كيفية استيراد وتقديم ملف للتحقق من صحته

تتضمن هذه المكتبة دعمًا لإرسال الملفات والتحقق من صحتها باستخدام عناوين البريد الإلكتروني، بما في ذلك:

  • ملفات نصية عادية (.txt)، مع عنوان بريد إلكتروني واحد في كل سطر؛
  • القيم المفصولة بفواصل (.csv)، والقيم المفصولة بعلامات جدولة (.tsv) وملفات القيم الأخرى المفصولة بفاصلات؛
  • جداول بيانات Microsoft Excel (.xls و.xlsx).

لإرسال الملفات والتحقق من صحتها، لا يزال بإمكان المرء استخدام طريقة SubmitAsync() المذكورة أعلاه، وتمرير إما Stream أو مثيل FileInfo أو مجرد byte[] مع محتوى الملف. إلى جانب ذلك، من الممكن أيضًا تحديد صفوف البداية والنهاية النهائية للمعالجة، والعمود، وفهرس الورقة، ونهاية السطر والمحدد - اعتمادًا بالطبع على طبيعة الملف المقدم (راجع FileValidationRequest في المصدر إلى يتعلم أكثر).

فيما يلي كيفية إرسال ملف Excel والتحقق منه، على سبيل المثال: 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( new FileInfo ( "that-file.xslx" ) ) ;

لمزيد من الخيارات المتقدمة، ما عليك سوى تمرير مثيل FileValidationRequest إلى الأسلوب SubmitAsync() : 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( new FileValidationRequest ( new FileInfo ( "that-file.xslx" ) )
        {
            Sheet = 3 ,
            StartingRow = 1 ,
            Column = 5
        } ,
        quality : QualityLevelName . High ) ;

وإليك مثال آخر يوضح كيفية إرسال مثيل Stream وتحديد نوع محتوى MIME للملف، والذي يتم تحديده تلقائيًا من امتداد الملف في حالة تمرير مثيل FileInfo : 

 Stream inputStream = .. . ; // TODO: Acquire the input data somehow

var job = await verifalia
    . EmailValidations
    . SubmitAsync ( inputStream ,
        MediaTypeHeaderValue . Parse ( WellKnownMimeContentTypes . TextPlain ) ) ; // text/plain

خيارات المعالجة

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

مستوى الجودة

تقدم Verifalia ثلاثة مستويات جودة متميزة - وهي القياسية والعالية والمتطرفة - والتي تستبعد كيفية تعامل محرك التحقق من البريد الإلكتروني مع مشكلات عدم التسليم المؤقتة، مع مبادلات البريد البطيئة وغيرها من المشكلات العابرة المحتملة التي يمكن أن تؤثر على جودة نتائج التحقق. تقبل التحميلات الزائدة لأسلوب SubmitAsync() معلمة quality تسمح بتحديد مستوى الجودة المطلوب؛ فيما يلي مثال يوضح كيفية التحقق من عنوان البريد الإلكتروني باستخدام مستوى الجودة العالية : 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( "[email protected]" , quality : QualityLevelName . High ) ;

وضع إلغاء البيانات المكررة

يسمح التحميل الزائد لأسلوب SubmitAsync() بقبول عناوين بريد إلكتروني متعددة في وقت واحد بتحديد كيفية التعامل مع الإدخالات المكررة المتعلقة بنفس مجموعة الإدخال؛ تدعم Verifalia وضع إلغاء البيانات المكررة الآمن ، الذي يلتزم بشدة بمعايير IETF القديمة، والوضع المريح الذي يتوافق أكثر مع ما يمكن العثور عليه في غالبية تكوينات مبادلات البريد الحالية.

في المثال التالي، نعرض كيفية استيراد قائمة عناوين البريد الإلكتروني والتحقق منها ووضع علامة على الإدخالات المكررة باستخدام وضع إلغاء البيانات المكررة المريح : 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( new FileInfo ( "that-file.xslx" ) , deduplication : DeduplicationMode . Relaxed ) ;

الاحتفاظ بالبيانات

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

من الممكن أيضًا تحديد سياسة الاحتفاظ بالبيانات لكل وظيفة والتي تحكم مدة بقاء مهمة التحقق من البريد الإلكتروني المقدمة؛ للقيام بذلك، استخدم التحميل الزائد لأسلوب SubmitAsync() الذي يقبل ValidationRequest أو مثيل FileValidationRequest ويقوم بتهيئة خاصية Retention الخاصة به وفقًا لذلك.

إليك كيفية، على سبيل المثال، تعيين سياسة الاحتفاظ بالبيانات لمدة 10 دقائق أثناء التحقق من عنوان البريد الإلكتروني: 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( new ValidationRequest ( new [ ]
    {
        "[email protected]"
    } )
    {
        Retention = TimeSpan . FromMinutes ( 10 )
    } ) ;

خيارات الانتظار

افتراضيًا، تقوم طريقة SubmitAsync() بإرسال مهمة التحقق من البريد الإلكتروني إلى Verifalia وانتظر اكتمالها؛ قد تتطلب العملية برمتها بعض الوقت حتى تكتمل اعتمادًا على خطة حساب Verifalia، وعدد عناوين البريد الإلكتروني التي يحتوي عليها الإرسال، ومستوى الجودة المحدد وعوامل الشبكة الأخرى بما في ذلك زمن استجابة مبادلات البريد قيد الاختبار.

في انتظار إكمال مهمة التحقق من البريد الإلكتروني، تقوم المكتبة تلقائيًا باستقصاء واجهة برمجة تطبيقات Verifalia الأساسية حتى تصبح النتائج جاهزة؛ بشكل افتراضي، يحاول الاستفادة من وضع الاستقصاء الطويل المقدم مع Verifalia API v2.4، والذي يسمح بتقليل عدد الطلبات والحصول على نتائج التحقق بشكل أسرع.

تجنب الانتظار

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

للقيام بذلك، من الممكن تحديد WaitOptions.NoWait كقيمة لمعلمة waitOptions الخاصة بعمليات التحميل الزائد لأسلوب SubmitAsync() ، كما هو موضح في المثال التالي: 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( new FileInfo ( "that-file.xslx" ) ,
        waitOptions : WaitOptions . NoWait ) ;

Console . WriteLine ( $ "Status: { job . Overview . Status } " ) ;
// Status: InProgress

تتبع التقدم

بالنسبة للوظائف التي تحتوي على عدد كبير من عناوين البريد الإلكتروني، قد يكون من المفيد تتبع التقدم أثناء معالجتها بواسطة محرك التحقق من البريد الإلكتروني Verifalia؛ للقيام بذلك، من الممكن إنشاء مثيل لفئة WaitOptions وتوفير معالج يتلقى في النهاية إشعارات التقدم من خلال خاصية Progress .

فيما يلي كيفية تحديد معالج إعلام التقدم الذي يعرض النسبة المئوية لتقدم المهمة المرسلة إلى نافذة وحدة التحكم: 

 var job = await verifalia
    . EmailValidations
    . SubmitAsync ( new FileInfo ( "that-other-file.csv" ) ,
        waitOptions : new WaitOptions
        {
            Progress = new Progress < ValidationOverview > ( overview =>
            {
                Console . WriteLine ( overview . Progress ? . Percentage ) ;
            } )
        } ) ;

عمليات الاسترجاعات الانتهاء

إلى جانب كل مهمة للتحقق من صحة البريد الإلكتروني، من الممكن تحديد عنوان URL الذي ستستدعيه Verifalia (POST) بمجرد اكتمال المهمة: يجب أن يستخدم عنوان URL هذا نظام HTTPS أو HTTP وأن يكون متاحًا للعامة عبر الإنترنت. لمعرفة المزيد حول عمليات الاسترجاعات الخاصة بالإكمال، يرجى الاطلاع على https://verifalia.com/developers#email-validations-completion-callback

لتحديد عنوان URL لرد اتصال الإكمال، قم بتمرير ValidationRequest أو FileValidationRequest إلى الأسلوب SubmitAsync() وقم بتعيين خاصية CompletionCallback الخاصة به وفقًا لذلك، كما هو موضح في المثال أدناه: 

 await verifalia
    . EmailValidations
    . SubmitAsync ( new ValidationRequest ( new [ ] { "[email protected]" } )
    {
        CompletionCallback = new CompletionCallback ( "https://your-website-here/foo/bar" )
    } ) ;

لاحظ أنه يتم استدعاء عمليات رد الاتصال الخاصة بالإكمال بشكل غير متزامن وقد يستغرق الأمر ما يصل إلى عدة ثوانٍ حتى يتم استدعاء عنوان URL لرد الاتصال الخاص بك.

إسترجاع الوظائف

من الممكن استرداد مهمة من خلال أساليب GetAsync() و GetOverviewAsync() ، والتي ترجع، على التوالي، مثيل Validation أو مثيل ValidationOverview لمهمة التحقق من البريد الإلكتروني المطلوبة. أثناء القيام بذلك، تنتظر المكتبة تلقائيًا اكتمال المهمة، ومن الممكن ضبط هذا السلوك عن طريق تمرير معلمة waitOptions إلى الطرق المذكورة أعلاه، بنفس الطريقة تمامًا كما هو موضح في التحميل الزائد لأسلوب SubmitAsync() ؛ يرجى الاطلاع على قسم خيارات الانتظار للحصول على تفاصيل إضافية.

فيما يلي مثال يوضح كيفية استرداد وظيفة، بالنظر إلى معرفها: 

 var jobId = Guid . Parse ( "ec415ecd-0d0b-49c4-a5f0-f35c182e40ea" ) ;
var job = await verifalia . EmailValidations . GetAsync ( jobId ) ;

تصدير نتائج التحقق من البريد الإلكتروني بتنسيقات إخراج مختلفة

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

تحذير : على الرغم من أن مخطط الإخراج (الأعمدة/التسميات/تنسيق البيانات) مكتمل إلى حد ما، يجب عليك دائمًا اعتباره عرضة للتغيير: استخدم أساليب GetAsync() / GetEntriesAsync() بدلاً من ذلك إذا كنت بحاجة إلى الاعتماد على مخطط إخراج مستقر.

فيما يلي مثال يوضح كيفية تصدير مهمة التحقق من البريد الإلكتروني كملف قيم مفصولة بفاصلة (CSV): 

 // Exports the validated entries for the job in the CSV format

var exportedStream = await verifalia
    . EmailValidations
    . ExportEntriesAsync ( new Guid ( "722c2fd8-8837-449f-ad24-0330c597c993" ) ,
        ExportedEntriesFormat . Csv ) ;

// Creates the output file stream

var fileStream = new FileStream ( "my-list.csv" , FileMode . Create ) ;

// Copies the exported stream into the output file stream

await exportedStream . CopyToAsync ( fileStream ) ;

لا تنس التنظيف عند الانتهاء

تقوم Verifalia بحذف المهام المكتملة تلقائيًا بعد اتباع سياسة الاحتفاظ بالبيانات القابلة للتكوين (راجع القسم ذي الصلة)، ولكن يُنصح بشدة بحذف المهام المكتملة في أقرب وقت ممكن، لأسباب تتعلق بالخصوصية والأمان. للقيام بذلك، يمكنك استدعاء الأسلوب DeleteAsync() لتمرير معرف المهمة الذي ترغب في التخلص منه: 

 await verifalia
    . EmailValidations
    . DeleteAsync ( job . Id ) ;

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

التكرار على وظائف التحقق من صحة البريد الإلكتروني الخاص بك

لأغراض الإدارة وإعداد التقارير، قد ترغب في الحصول على قائمة مفصلة بمهام التحقق من صحة البريد الإلكتروني السابقة. تسمح مكتبة SDK هذه بالقيام بذلك من خلال الأسلوب ListAsync() ، الذي يسمح بالتكرار بشكل غير متزامن عبر مجموعة من مثيلات ValidationOverview (نفس نوع الخاصية Overview للنتائج التي يتم إرجاعها بواسطة SubmitAsync() و GetAsync() ).

فيما يلي كيفية التكرار على وظائفك، من الأحدث إلى الأقدم: 

 var jobOverviews = verifalia
    . EmailValidations
    . ListAsync ( new ValidationOverviewListingOptions
    {
        Direction = Direction . Backward
    } ) ;

await foreach ( var jobOverview in jobOverviews )
{
    Console . WriteLine ( "Id: {0}, status: {2}, entries: {3}" ,
        jobOverview . Id ,
        jobOverview . Status ,
        jobOverview . NoOfEntries ) ;
}

// Prints out something like:
// Id: a7784f9a-86d4-436c-b8e4-f72f2bd377ac, status: InProgress, entries: 9886
// Id: 86d57c00-147a-4736-88cc-c918260c67c6, status: Completed, entries: 1
// Id: 594bbb0f-6f12-481c-926f-606cfefc1cd5, status: Completed, entries: 1
// Id: a5c1cd5b-39cc-43bc-9a3a-ee4a0f80ee6d, status: InProgress, entries: 226
// Id: b6f69e30-60dd-4c21-b2cb-e73ba75fb278, status: Completed, entries: 12077
// Id: 5e5a97dc-459f-4edf-a607-47371c32aa94, status: Deleted, entries: 1009
// ...

يستخدم أسلوب ListAsync() ميزة C# 8.0 غير المتزامنة القابلة للتعداد ؛ للحصول على دعم اللغة السابق، يرجى التحقق من مجموعة أساليب ListSegmentedAsync() .

تصفية وظائف التحقق من صحة البريد الإلكتروني

تتمتع طريقة ListAsync() أيضًا بالقدرة، عن طريق وسيطة options نفسها، على تصفية وظائف التحقق من البريد الإلكتروني التي يتم إرجاعها بواسطة Verifalia API: من الممكن التصفية حسب تاريخ الإرسال والمالك وحالة الوظائف.

فيما يلي كيفية تكرار عملية الإدراج الموضحة في المثال أعلاه، وهذه المرة يتم إرجاع وظائف مستخدم معين فقط وفي نطاق زمني محدد: 

 var jobOverviews = verifalia
    . EmailValidations
    . ListAsync ( new ValidationOverviewListingOptions
    {
        Direction = Direction . Backward ,
        CreatedOn = new DateBetweenPredicate ( new DateTime ( 2024 , 1 , 3 ) ,
            new DateTime ( 2024 , 1 , 7 ) ) ,
        Owner = new StringEqualityPredicate ( "50173acd-9ed2-4298-ba7f-8ccaeed48deb" )
    } ) ;

await foreach ( var jobOverview in jobOverviews )
{
    // ...
}

إدارة الاعتمادات

لإدارة أرصدة Verifalia لحسابك، يمكنك استخدام خاصية Credits التي يعرضها مثيل VerifaliaRestClient الذي تم إنشاؤه أعلاه. كما هو الحال في الموضوع السابق، سننظر في الفقرات القليلة التالية إلى العمليات الأكثر استخدامًا، لذا يُنصح بشدة باستكشاف المكتبة والنظر إلى تعليمات xmldoc المضمنة للحصول على فرص أخرى.

الحصول على رصيد الاعتمادات

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

 var balance = await verifalia
    . Credits
    . GetBalanceAsync ( ) ;

Console . WriteLine ( "Credit packs: {0}, free daily credits: {1} (will reset in {2})" ,
	balance . CreditPacks ,
	balance . FreeCredits ,
	balance . FreeCreditsResetIn ) ;

// Prints out something like:
// Credit packs: 956.332, free daily credits: 128.66 (will reset in 09:08:23)

لإضافة حزم الائتمان إلى حساب Verifalia الخاص بك، تفضل بزيارة https://verifalia.com/client-area#/credits/add.

استرجاع إحصائيات استخدام الاعتمادات

كوسيلة لمراقبة استهلاك الاعتمادات لحسابك والتنبؤ به، تسمح الطريقة ListDailyUsagesAsync() باسترداد إحصائيات حول استخدام الاعتمادات التاريخية، مما يؤدي إلى إرجاع مجموعة قابلة للتكرار بشكل غير متزامن من مثيلات DailyUsage . تسمح الطريقة أيضًا بتحديد فترة الاهتمام عن طريق تمرير مثيل DailyUsageListingOptions . يتم إرجاع العناصر فقط للتواريخ التي حدث فيها الاستهلاك (إما من الأرصدة المجانية أو حزم الائتمان أو كليهما).

وإليك كيفية استرجاع الاستهلاك اليومي للأرصدة لآخر ثلاثين يومًا: 

 var dailyUsages = verifalia
    . Credits
    . ListDailyUsagesAsync ( new DailyUsageListingOptions
	{
        DateFilter = new DateBetweenPredicate
        {
            Since = DateTime . Now . AddDays ( - 30 )
        }
    } ) ;

await foreach ( var dailyUsage in dailyUsages )
{
    Console . WriteLine ( "{0:yyyyMMdd} - credit packs: {1}, free daily credits: {2}" ,
        dailyUsage . Date ,
        dailyUsage . CreditPacks ,
        dailyUsage . FreeCredits ) ;
}

// Prints out something like:
// 20240201 - credit packs: 1965.68, free daily credits: 200
// 20240126 - credit packs: 0, free daily credits: 185.628
// 20240125 - credit packs: 15.32, free daily credits: 200
// ...

يستخدم أسلوب ListDailyUsagesAsync() ميزة C# 8.0 غير القابلة للتعداد ؛ للحصول على دعم اللغة السابق، يرجى التحقق من مجموعة أساليب ListDailyUsagesSegmentedAsync() .

سجل التغيير / ما الجديد

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

v4.2

تم إصداره في 11 يناير 2024

  • تمت إضافة الدعم لواجهة برمجة التطبيقات v2.5
  • تمت إضافة دعم لقواعد تجاوز التصنيف
  • تمت إضافة دعم للاقتراحات المدعومة بالذكاء الاصطناعي
  • تمت إضافة دعم لـ .NET 8.0
  • التبعيات صدم

v4.1

تم إصداره في 26 مايو 2023

  • تمت إضافة دعم للمرشحات عند إدراج وظائف التحقق من البريد الإلكتروني
  • تم حل مشكلة تتعلق بأسلوب ToAsyncEnumerableAsync() والتي كانت تؤدي سابقًا إلى قوائم غير مكتملة في سيناريوهات محددة

v4.0

تم إصداره في 27 فبراير 2023

  • تمت إضافة دعم لواجهة برمجة التطبيقات v2.4
  • تمت إضافة دعم لـ .NET 7.0
  • تمت إضافة دعم لخيارات رد الاتصال الجديدة للإكمال
  • تمت إضافة دعم للكشف عن مبادلات البريد المتوقفة
  • تمت إضافة دعم لتحديد وقت انتظار مخصص أثناء إرسال واسترجاع مهام التحقق من البريد الإلكتروني
  • تمت إضافة دعم للتعليقات التوضيحية الفارغة
  • التغيير العاجل: إعادة تسمية WaitingStrategy إلى WaitOptions وإعادة هيكلة الأخير بحيث يسمح الآن بضبط أوقات انتظار الاستقصاء الأساسية
  • تغيير جذري: السلوك الافتراضي لتقديم الوظيفة واسترجاعها هو الآن انتظار اكتمال المهام (ولكن من الممكن تغيير ذلك من خلال فئة WaitOptions الجديدة)
  • تغيير جذري: تشير خاصية CompletionCallback لفئتي ValidationRequest و FileValidationRequest الآن إلى فئة CompletionCallback كاملة بدلاً من Uri البسيط
  • التبعيات المتصادمة (بما في ذلك Newtonsoft.Json وFlurl)
  • تحسين الوثائق
يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل