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

تعرف على كل شيء عن Fetch API ، وهو النهج الحديث لطلبات الشبكة غير المتزامنة التي تستخدم Promises ككتلة بناء

مقدمة إلى Fetch API

منذ إصدار IE5 في عام 1998 ، كان لدينا خيار إجراء مكالمات شبكة غير متزامنة في المتصفح باستخدامXMLHttpRequest(XHR).

بعد سنوات قليلة من ذلك ، استفاد GMail والتطبيقات الغنية الأخرى منه بشكل مكثف ، وجعل هذا النهج شائعًا لدرجة أنه كان يجب أن يكون له اسم:أجاكس.

لطالما كان العمل مباشرة مع XMLHttpRequest أمرًا مزعجًا وقد تم تجريده دائمًا من قبل بعض المكتبات ، ولا سيما jQuery له وظائف مساعدة خاصة به مبنية حوله:

  • jQuery.ajax()
  • jQuery.get()
  • jQuery.post()

وهكذا.

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

الجلب API، تم توحيده كنهج حديث لطلبات واستخدامات الشبكة غير المتزامنةوعودكحجر بناء.

يتمتع Fetch بدعم جيد عبر المتصفحات الرئيسية ، باستثناء IE.

The browser support for the Fetch API

بوليفيلhttps://github.com/github/fetchصدر من قبلجيثبيسمح لنا باستخدامfetchعلى أي متصفح.

باستخدام الجلب

إن بدء استخدام طلبات الجلب للحصول على طلبات الحصول على المعلومات أمر بسيط للغاية:

fetch('/file.json')

وأنت تستخدمه بالفعل: سيؤدي الجلب إلى تقديم طلب HTTP للحصول على ملفfile.jsonالموارد في نفس المجال.

كما ترى ، فإنfetchوظيفة متاحة في العالمwindowالكائن.

الآن لنجعل هذا أكثر فائدة ، دعنا نرى ما هو محتوى الملف:

fetch('./file.json')
  .then(response => response.json())
  .then(data => console.log(data))

الاتصالfetch()إرجاع أيعد. يمكننا بعد ذلك انتظار حل الوعد عن طريق تمرير معالج بامتدادthen()طريقة الوعد.

يتلقى هذا المعالج القيمة المرجعة لـfetchالوعد ، أإجابةموضوع.

سنرى هذا الكائن بالتفصيل في القسم التالي.

اصطياد الأخطاء

منذfetch()يعود بوعد ، يمكننا استخدامcatchطريقة الوعد باعتراض أي خطأ يحدث أثناء تنفيذ الطلب ، وتتم المعالجة فيthenعمليات الاسترجاعات:

fetch('./file.json')
.then(response => {
  //...
})
.catch(err => console.error(err))

هناك طريقة أخرى لاكتشاف الأخطاء وهي إدارتها في البدايةthen:

fetch('./file.json')
.then(response => {
  if (!response.ok) { throw Error(response.statusText) }
  return response
})
.then(response => {
  //...
})

كائن الاستجابة

تم إرجاع كائن الاستجابة بواسطة afetch()تحتوي المكالمة على جميع المعلومات المتعلقة بالطلب واستجابة طلب الشبكة.

البيانات الوصفية

رؤوس

الوصول إلىheadersالممتلكات علىresponseيمنحك الكائن القدرة على النظر في رؤوس HTTP التي تم إرجاعها بواسطة الطلب:

fetch('./file.json').then(response => {
  console.log(response.headers.get('Content-Type'))
  console.log(response.headers.get('Date'))
})

Request headers for fetch

الحالة

هذه الخاصية هي رقم صحيح يمثل حالة استجابة HTTP.

  • 101 أو 204 أو 205 أو 304 هي حالة نصية فارغة
  • 200 إلى 299 ، ضمناً ، هي حالة جيدة (نجاح)
  • 301 أو 302 أو 303 أو 307 أو 308 هي إعادة توجيه

    fetch('./file.json').then(response => console.log(response.status))
    

الحالة

statusTextهي خاصية تمثل رسالة حالة الاستجابة. إذا كان الطلب ناجحًا ، تكون الحالةOK.

fetch('./file.json').then(response => console.log(response.statusText))

عنوان url

urlيمثل عنوان URL الكامل للممتلكات التي جلبناها.

fetch('./file.json').then(response => console.log(response.url))

محتوى الجسم

الرد له جسم يمكن الوصول إليه بعدة طرق:

  • text()إرجاع الجسم كسلسلة
  • json()يعيد الجسم كملفجسونكائن موزّع
  • blob()يعيد الجسم كملفسائل لزجموضوع
  • formData()إرجاع النص ككائن FormData
  • arrayBuffer()يعيد الجسم كملفArrayBufferموضوع

كل هذه الأساليب تعيد الوعد. أمثلة:

fetch('./file.json')
  .then(response => response.text())
  .then(body => console.log(body))
fetch('./file.json')
  .then(response => response.json())
  .then(body => console.log(body))

Get JSON

يمكن كتابة نفس الشيء باستخدامES2017 وظائف غير متزامنة:

;(async () => {
  const response = await fetch('./file.json')
  const data = await response.json()
  console.log(data)
})()

طلب كائن

يمثل كائن Request طلب مورد ، وعادة ما يتم إنشاؤه باستخدام الامتدادnew Request()API.

مثال:

const req = new Request('/api/todos')

يقدم كائن Request عدة خصائص للقراءة فقط لفحص تفاصيل طلب المورد ، بما في ذلك

  • method: طريقة الطلب (GET ، POST ، إلخ.)
  • url: عنوان URL للطلب.
  • headers: كائن الرؤوس المرتبط بالطلب
  • referrer: محيل الطلب
  • cache: وضع ذاكرة التخزين المؤقت للطلب (على سبيل المثال ، الافتراضي ، إعادة التحميل ، عدم التخزين المؤقت).

ويكشف عدة طرق منهاjson()وtext()وformData()لمعالجة نص الطلب.

يمكن العثور على واجهة برمجة التطبيقات الكاملة علىhttps://developer.mozilla.org/docs/Web/API/Request

طلب الرؤوس

تعد القدرة على تعيين رأس طلب HTTP أمرًا ضروريًا ، وfetchيمنحنا القدرة على القيام بذلك باستخدام كائن الرؤوس:

const headers = new Headers()
headers.append('Content-Type', 'application/json')

أو:

const headers = new Headers({
  'Content-Type': 'application/json'
})

لإرفاق الرؤوس بالطلب ، نستخدم الكائن Request ، ونمرره إليهfetch()بدلاً من تمرير عنوان URL.

بدلا من:

fetch('./file.json')

نحن نفعل

const request = new Request('./file.json', {
  headers: new Headers({
    'Content-Type': 'application/json'
  })
})
fetch(request)

لا يقتصر كائن الرؤوس على تحديد القيمة ، ولكن يمكننا أيضًا الاستعلام عنها:

headers.has('Content-Type')
headers.get('Content-Type')

ويمكننا حذف رأس تم تعيينه مسبقًا:

headers.delete('X-My-Custom-Header')

طلبات POST

يسمح Fetch أيضًا باستخدام أي طريقة HTTP أخرى في طلبك: POST أو PUT أو DELETE أو OPTIONS.

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

مثال على طلب POST:

const options = {
  method: 'post',
  headers: {
    'Content-type': 'application/x-www-form-urlencoded; charset=UTF-8'
  },
  body: 'name=Flavio&test=1'
}

fetch(url, options).catch(err => { console.error(‘Request failed’, err) })

كيفية إلغاء طلب الجلب

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

يمكننا الآن ، بفضل إدخالAbortControllerوAbortSignal، واجهة برمجة تطبيقات عامة للإعلامإجهاضالأحداث

يمكنك دمج واجهة برمجة التطبيقات هذه عن طريق تمرير إشارة كمعامل جلب:

const controller = new AbortController()
const signal = controller.signal

fetch(’./file.json’, { signal })

يمكنك تعيين مهلة تؤدي إلى حدث إحباط بعد 5 ثوانٍ من بدء طلب الجلب ، لإلغائه:

setTimeout(() => controller.abort(), 5 * 1000)

ملائم ، إذا عاد الجلب بالفعل ، فسيتصلabort()لن يسبب أي خطأ.

عندما تحدث إشارة إحباط ، سيرفض الجلب الوعد بامتدادDOMExceptionاسم الشيئAbortError:

fetch('./file.json', { signal })
  .then(response => response.text())
  .then(text => console.log(text))
  .catch(err => {
    if (err.name === 'AbortError') {
      console.error('Fetch aborted')
    } else {
      console.error('Another error', err)
    }
  })

اتبحث عن المزيد؟

العمل مع الشبكة صعب ، أليس كذلك؟ قد تجد أن ملفأكسيوسقد تكون مكتبة JavaScript مناسبة بشكل أفضل لاحتياجاتك مع بعض الميزات الإضافية المبنية على Fetch. تحقق من ذلك!


المزيد من دروس المتصفح: