Geekly articles weekly

أتمتة أصغر. الملاحظات. API مريحة

هذه المقالة هي واحدة من الملاحظات القصيرة الموعودة خلال سلسلة المقالات " أتمتة للأصغر" .
نظرًا لأن RESTful API هي الطريقة الرئيسية للتفاعل مع نظام IPAM ، فقد قررت التحدث عن ذلك بشكل منفصل.


أعطي الثناء للمهندسين المعماريين في العالم الحديث - لدينا واجهات موحدة. نعم ، هناك الكثير منهم - هذا ناقص ، لكنهم - هذا زائد.

اكتسبت هذه الواجهات اسم API - واجهة برمجة التطبيقات.

إحدى هذه الواجهات هي واجهة برمجة تطبيقات RESTful ، والتي تُستخدم للعمل مع NetBox.



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

على سبيل المثال ، في حالة NetBox ، يمكنك إضافة جهاز جديد إليه بالطرق التالية: من خلال متصفح ويب أو إرسال طلب curl'om في وحدة التحكم أو استخدام Postman أو الوصول إلى مكتبة الطلبات في python أو استخدام pynetbox SDK أو الانتقال إلى Swagger.

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

محتوى


  • الراحة ، الراحة ، API
  • هيكل رسالة HTTP
    • خط البداية
    • عناوين
    • نص رسالة HTTP

  • طرق
    • HTTP GET
    • HTTP POST
    • HTTP PUT
    • تصحيح HTTP
    • HTTP الحذف

  • طرق للعمل مع RESTful API
    • الضفيرة
    • ساعي البريد
    • بيثون + طلبات
    • Pynebtbox SDK
    • اختيال

  • نقد الراحة والبدائل
  • روابط مفيدة

الراحة ، الراحة ، API


أدناه ، سأقدم وصفًا مبسطًا للغاية لماهية REST.

بادئ ذي بدء ، واجهة برمجة تطبيقات RESTful هي واجهة التفاعل القائمة على REST ، في حين أن REST ( نقل الحالة التمثيلية ) نفسها عبارة عن مجموعة من القيود المستخدمة لإنشاء خدمات WEB.

من الممكن أن تقرأ بالضبط ما هي القيود التي يمكن العثور عليها في الفصل 5 من أطروحة روي فيلدنج ، والأنماط المعمارية وتصميم هندسة البرمجيات القائمة على الشبكة . اسمحوا لي أن أقدم لكم أهم ثلاثة فقط (من وجهة نظري) منهم:

  1. يستخدم بنية REST طراز التفاعل Client-Server.
  2. يحتوي كل طلب REST على كافة المعلومات اللازمة لتنفيذه. بمعنى أنه لا ينبغي أن يتذكر الخادم أي شيء عن طلبات العميل السابقة ، والتي ، كما تعلمون ، تتميز بكلمة "بلا جنسية" - لا تقم بتخزين معلومات الحالة.
  3. واجهة موحدة. تطبيق التطبيق منفصل عن الخدمة التي يقدمها. أي أن المستخدم يعرف ما يفعله وكيف يتفاعل معه ، لكن كيف يفعله لا يهم. عند تغيير التطبيق ، تظل الواجهة كما هي ، ولن يحتاج العملاء إلى ضبطها.

تسمى خدمات WEB التي تفي بجميع مبادئ REST خدمات WEB RESTful .

وتسمى واجهة برمجة التطبيقات التي توفر خدمات RESTful WEB بـ RESTful API.

REST ليس بروتوكولًا ، ولكن ما يسمى بنمط العمارة (أحد). تم تطويره باستخدام HTTP بواسطة Roy Fielding ، وكان الغرض من REST هو استخدام HTTP 1.1 كوسيلة نقل.

عنوان الوجهة (أو بعبارة أخرى - كائن ، أو بطريقة أخرى - نقطة نهاية) - هذا هو عنوان URL المعتاد الخاص بنا.

تنسيق البيانات المرسلة هو XML أو JSON .
بالنسبة إلى هذه السلسلة من المقالات حول linkmeup ، تم نشر نشر للقراءة فقط (بالنسبة لك ، القراء الأعزاء) .تثبيت NetBox: netbox.linkmeup.ru : 45127.

حقوق القراءة غير مطلوبة ، ولكن إذا كنت ترغب في محاولة القراءة باستخدام رمز مميز ، فيمكنك استخدام هذا: Token API: 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8 .
لنقدم طلبًا واحدًا للمتعة:

curl -X GET -H "Authorization: TOKEN 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8" \ -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/1/

هذا هو ، مع الأداة المساعدة curl ، نصنع كائن GET على netbox.linkmeup.ru : 45127 / api / dcim / devices / 1 / مع استجابة JSON ومسافة بادئة 4 مسافات.

أو أكثر قليلاً من الناحية الأكاديمية: تقوم GET بإرجاع كائن الأجهزة المكتوبة ، والذي يعد معلمة لكائن DCIM .

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

 { "id": 1, "name": "mlg-host-0", "display_name": "mlg-host-0", "device_type": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/device-types/4/", "manufacturer": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/manufacturers/4/", "name": "Hypermacro", "slug": "hypermacro" }, "model": "Server", "slug": "server", "display_name": "Hypermacro Server" }, "device_role": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/device-roles/1/", "name": "Server", "slug": "server" }, "tenant": null, "platform": null, "serial": "", "asset_tag": null, "site": { "id": 6, "url": "http://netbox.linkmeup.ru/api/dcim/sites/6/", "name": "", "slug": "mlg" }, "rack": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/racks/1/", "name": "A", "display_name": "A" }, "position": 41, "face": { "value": "front", "label": "Front", "id": 0 }, "parent_device": null, "status": { "value": "active", "label": "Active", "id": 1 }, "primary_ip": null, "primary_ip4": null, "primary_ip6": null, "cluster": null, "virtual_chassis": null, "vc_position": null, "vc_priority": null, "comments": "", "local_context_data": null, "tags": [], "custom_fields": {}, "config_context": {}, "created": "2020-01-14", "last_updated": "2020-01-14T18:39:01.288081Z" }

هذا هو JSON (كما طلبنا) ، حيث يصف الجهاز بمعرف 1: ما يسمى ، وما هو الدور ، والنموذج ، والمكان الذي يقف فيه ، إلخ.

سيبدو هذا كطلب HTTP:

  GET /api/dcim/devices/1/ HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4


لذلك سوف تبدو الإجابة:
  HTTP/1.1 200 OK Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive Data

تفريغ المعاملة .

الآن دعونا نتعرف على ما قمنا به.


هيكل رسالة HTTP


تتكون رسالة HTTP من ثلاثة أجزاء ، الأول فقط هو المطلوب.

  • خط البداية
  • عناوين
  • نص الرسالة

خط البداية


تبدو خطوط البدء لطلب HTTP والاستجابة مختلفة.

طلب HTTP


 METHOD URI HTTP_VERSION

تحدد الطريقة الإجراء الذي يريد العميل تنفيذه: استلام البيانات ، إنشاء كائن ، تحديثه ، حذفه.
URI - معرف المورد الذي يصل إليه العميل ، أو بمعنى آخر ، المسار إلى المورد / المستند.
HTTP_VERSION هو إصدار HTTP ، على التوالي. اليوم ، بالنسبة لـ REST ، فهو دائمًا 1.1.
مثال:

 GET /api/dcim/devices/1/ HTTP/1.1


استجابة HTTP


 HTTP_VERSION STATUS_CODE REASON_PHRASE

HTTP_VERSION - إصدار HTTP (1.1).
STATUS_CODE - ثلاثة أرقام من رمز الحالة (200 ، 404 ، 502 ، إلخ)
REASON_PHRASE - شرح (حسنًا ، غير موجود ، بوابة سيئة ، إلخ.)

مثال:

 HTTP/1.1 200 OK

عناوين


تمر الرؤوس المعلمات لمعاملة HTTP هذه.

على سبيل المثال ، في المثال أعلاه في طلب HTTP ، كانت هذه:

  Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4

أنها تشير إلى ذلك

  1. ننتقل إلى المضيف netbox.linkmeup.ru:45127 ،
  2. تم إنشاء الطلب في حليقة ،
  3. ونحن نقبل البيانات بتنسيق JSON مع المسافة البادئة 4 .

وإليك العناوين في استجابة HTTP:

  Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive

أنها تشير إلى ذلك

  1. نوع الخادم: nginx على أوبونتو ،
  2. وقت الاستجابة
  3. تنسيق بيانات الاستجابة: JSON
  4. طول بيانات الاستجابة: 1638 بايت
  5. لا يلزم إغلاق الاتصال - ستظل هناك بيانات.

تبدو الرؤوس ، كما لاحظت بالفعل ، مثل الاسم: أزواج القيمة ، مفصولة بعلامة ":".

قائمة كاملة من الرؤوس المحتملة .

نص رسالة HTTP


يستخدم الجسم لنقل البيانات الفعلية.

في استجابة HTTP ، يمكن أن تكون هذه صفحة HTML ، أو في حالتنا كائن JSON.

يجب أن يكون هناك سطر فارغ واحد على الأقل بين الرؤوس والجسم.

عند استخدام طريقة GET في طلب HTTP ، لا يوجد عادة نص لأنه لا يوجد شيء للإرسال. لكن الجسم في استجابة HTTP.

ولكن على سبيل المثال ، مع POST ، سيكون الجسم بالفعل في الطلب. دعونا نتحدث عن الأساليب والتحدث الآن.


طرق


كما فهمت بالفعل ، يستخدم HTTP أساليب للعمل مع خدمات WEB. الشيء نفسه ينطبق على RESTful API.

يتم وصف سيناريوهات الحياة الحقيقية المحتملة بمصطلح CRUD - إنشاء ، قراءة ، تحديث ، حذف .
فيما يلي قائمة بأساليب HTTP الأكثر شيوعًا التي تنفذ CRUD:

  • HTTP GET
  • HTTP POST
  • HTTP PUT
  • HTTP الحذف
  • تصحيح HTTP

وتسمى الأساليب أيضًا الأفعال ، لأنها تشير إلى الإجراء الذي يتم تنفيذه.

قائمة كاملة من الطرق .

دعونا نلقي نظرة على كل منهم باستخدام مثال NetBox.

HTTP GET


هذه طريقة للحصول على المعلومات.

لذلك ، على سبيل المثال ، نأخذ قائمة الأجهزة:

 curl -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/

طريقة GET آمنة لأنها لا تغير البيانات ، ولكن فقط يسأل.

ومن العاطفي من وجهة نظر أن نفس الاستعلام دائما بإرجاع نفس النتيجة (حتى يتم تغيير البيانات نفسها).

في GET ، يعرض الخادم رسالة برمز HTTP ونص الاستجابة ( رمز الاستجابة ونص الاستجابة ).

هذا هو ، إذا كان كل شيء على ما يرام ، فإن رمز الاستجابة هو 200 (موافق).
إذا لم يتم العثور على عنوان URL ، 404 (غير موجود).
إذا حدث خطأ ما في الخادم أو المكونات نفسها ، فيمكن أن يكون 500 (خطأ في الخادم) أو 502 (BAD GATEWAY).
جميع رموز الاستجابة الممكنة .

يتم إرجاع النص بتنسيق JSON أو XML.

تفريغ المعاملة .

دعنا نعطي بضعة أمثلة أخرى. الآن سوف نطلب معلومات على جهاز معين باسمه.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0"

هنا ، لتعيين شروط البحث في URI ، حددت أيضًا سمة الكائن (معلمة الاسم وقيمته mlg-leaf-0 ). كما ترون ، قبل الشرط وبعد شرطة مائلة هناك "؟" ، والاسم والقيمة مفصولة بعلامة "=" .

هذا هو ما يبدو الطلب.

  GET /api/dcim/devices/?name=mlg-leaf-0 HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4

تفريغ المعاملة .

إذا كنت بحاجة إلى تحديد شرطين ، فسيبدو الاستعلام كما يلي:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?role=leaf&site=mlg"

هنا طلبنا جميع الأجهزة ورقة تقع على موقع mlg .
بمعنى ، يتم فصل الشرطين عن بعضهما البعض بواسطة علامة "&" .

تفريغ المعاملة .

من الفضوليين والبهجة - إذا قمت من خلال "&" بضبط شرطين بنفس الاسم ، فلن يكون بينهما في الواقع "AND" منطقي ، بل "OR" منطقي.

بمعنى أن مثل هذا الاستعلام سيعيد كائنين فعليين: mlg-leaf-0 و mlg-spine-0

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0&name=mlg-spine-0"

تفريغ المعاملة .

دعنا نحاول الوصول إلى عنوان URL غير موجود.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/IDGAF/"

تفريغ المعاملة .


HTTP POST


يستخدم POST لإنشاء كائن جديد في مجموعة من الكائنات. أو بلغة أكثر تعقيدًا: لإنشاء مورد فرعي جديد.

توضيح من arthuriantech :
بما في ذلك ، ولكن ليس على سبيل الحصر. تم تصميم طريقة POST لنقل البيانات إلى الخادم لمزيد من المعالجة - يتم استخدامها لأية إجراءات لا تحتاج إلى توحيدها ضمن HTTP. قبل RFC 5789 ، كانت الطريقة القانونية الوحيدة لإجراء تغييرات جزئية.
roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
tools.ietf.org/html/rfc7231#section-4.3.3


أي إذا كان هناك مجموعة من الأجهزة ، فإن POST يسمح لك بإنشاء كائن جهاز جديد داخل الأجهزة.

حدد نقطة النهاية نفسها واستخدم POST لإنشاء جهاز جديد.

 curl -X POST "http://netbox.linkmeup.ru:45127/api/dcim/devices/" \ -H "accept: application/json"\ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\"}"

يظهر رأس التخويل بالفعل هنا ، يحتوي على رمز مميز يرخص طلب الكتابة ، وبعد توجيه -d هناك JSON مع معلمات الجهاز الذي تم إنشاؤه:

 { "name": "just a simple russian girl", "device_type": 1, "device_role": 1, "site": 3, "rack": 3, "position": 5, "face": "front"}

لن يعمل طلبك ، لأن الرمز لم يعد صالحًا - لا تحاول الكتابة إلى NetBox.
تأتي الاستجابة مع استجابة HTTP مع الرمز 201 (CREATED) و JSON في نص الرسالة ، حيث يعرض الخادم جميع المعلمات حول الجهاز الذي تم إنشاؤه.

  HTTP/1.1 201 Created Server: nginx/1.14.0 (Ubuntu) Date: Sat, 18 Jan 2020 11:00:22 GMT Content-Type: application/json Content-Length: 1123 Connection: keep-alive JSON

تفريغ المعاملة .

الآن ، مع طلب جديد باستخدام طريقة GET ، يمكنك رؤيته في الإخراج:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?q=russian"

يسمح لك "Q" في NetBox بالعثور على كل الكائنات التي تحتوي على اسمهم بخط يمتد إلى أبعد من ذلك.
من الواضح أن POST ليس آمناً ولا عاطفيًا - من المحتمل أن يغير البيانات ، وسيؤدي طلب التنفيذ المزدوج إما إلى إنشاء الكائن الثاني نفسه أو إلى خطأ.


HTTP PUT


هذه طريقة لتعديل كائن موجود. تبدو نقطة النهاية لـ PUT مختلفة عن POST - فهي تحتوي الآن على كائن محدد.

يمكن أن يعرض PUT الأكواد 201 أو 200.

نقطة مهمة في هذه الطريقة: يجب أن تمر كل السمات المطلوبة ، لأن PUT يستبدل الكائن القديم.

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

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"asset_tag\": \"12345678\"}" 

 {"device_type":["This field is required."],"device_role":["This field is required."],"site":["This field is required."]}

ولكن إذا أضفت الحقول المفقودة ، فسيعمل كل شيء:

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\", \"asset_tag\": \"12345678\"}"

تفريغ المعاملة .
انتبه إلى عنوان URL هنا - وهو الآن يتضمن معرّف الجهاز الذي نريد تغييره ( 18 ).


تصحيح HTTP


يتم استخدام هذه الطريقة لتعديل المورد جزئيًا.
WAT؟ أنت تسأل ، ولكن ماذا عن وضع؟

PUT هي طريقة موجودة أصلاً في المعيار ، تتضمن الاستبدال الكامل لكائن قابل للتغيير. وفقًا لذلك ، في طريقة PUT ، كما كتبت أعلاه ، سيتعين عليك تحديد حتى سمات الكائن التي لا تتغير.

تمت إضافة PATCH لاحقًا ويتيح لك تحديد السمات التي تتغير فعليًا فقط.

على سبيل المثال:

 curl -X PATCH "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"serial\": \"BREAKINGBAD\"}"

هنا ، يتم تحديد معرف الجهاز أيضًا في عنوان URL ، ولكن هناك سمة متسلسلة واحدة فقط يجب تغييرها.

تفريغ المعاملة .


HTTP الحذف


من الواضح أن يحذف الكائن.

مثال

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f"

تعتبر طريقة DELETE غير محددة من وجهة نظر أن الاستعلام المتكرر لم يعد يغير أي شيء في قائمة الموارد (لكن سيعود الرمز 404 (غير موجود).

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" 

 {"detail":"Not found."}


طرق للعمل مع RESTful API


كورل ، بالطبع ، مناسب جدًا لمحاربي CLI الشجعان ، ولكن هناك أدوات أفضل.

ساعي البريد


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

بالإضافة إلى ذلك ، يمكن حفظ الاستعلامات ووحدات URI وإعادتها إليها لاحقًا.

تحميل ساعي البريد على الموقع الرسمي .

لذلك يمكننا أن نفعل الحصول على:


يشار إلى الرمز المميز هنا في GET كمثال فقط.

وبعد ذلك:



ساعي البريد للاستخدام مع RESTful API فقط.
على سبيل المثال ، لا تحاول إرسال NETCONF XML عبره ، كما فعلت في فجر مسيرتي التلقائية.
أحد المكافآت اللطيفة لواجهة برمجة التطبيقات المحددة هو أنه يمكنك استيراد جميع نقاط النهاية وأساليبها إلى ساعي البريد كمجموعة.

للقيام بذلك ، في نافذة " استيراد" (ملف-> استيراد) ، حدد " استيراد من الرابط" والصقه في نافذة netbox.linkmeup.ru URL: 45127 / api / docs /؟ Format = openapi.



علاوة على ذلك ، كل ما يمكنك العثور عليه في المجموعات.





طلبات بيثون +


لكن حتى من خلال Postman ، من المحتمل ألا تدير أنظمة الإنتاج الخاصة بك. بالتأكيد ، سيكون لديك تطبيقات خارجية تريد التفاعل معها دون مشاركتك.

على سبيل المثال ، يريد نظام إنشاء التكوين انتقاء قائمة بواجهات IP من NetBox.
بيثون لديها مكتبة رائعة من الطلبات التي تنفذ العمل من خلال HTTP.
مثال على طلب قائمة بجميع الأجهزة:

 import requests HEADERS = {'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" devices = requests.get(request_url, headers = HEADERS) print(devices.json())

أضف جهازًا جديدًا مرة أخرى:

 import requests API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" HEADERS = {'Authorization': f'Token {API_TOKEN}', 'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" device_parameters = { "name": "just a simple REQUESTS girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = requests.post(request_url, headers = HEADERS, json=device_parameters) print(new_device.json())


Python + NetBox SDK


في حالة NetBox ، يوجد أيضًا Python SDK - Pynetbox ، والذي يمثل جميع نقاط نهاية NetBox ككائن وسماته ، ويقوم بكل الأعمال القذرة لتوليد URIs وتحليل الاستجابة ، وإن لم يكن مجانًا ، بالطبع.

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

 import pynetbox NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL) devices = nb.dcim.devices.all() print(devices)

إضافة جهاز جديد:

 import pynetbox API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL, token = API_TOKEN) device_parameters = { "name": "just a simple PYNETBOX girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = nb.dcim.devices.create(**device_parameters) print(new_device)

Pynetbox الوثائق


اختيال


ما يستحق آخر بفضل العقد الماضي هو مواصفات API. إذا اتبعت هذا المسار ، فسيتم نقلك إلى وثائق Swagger UI - Netbox API.



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



في نفس الصفحة ، يمكنك إجراء استعلامات تفاعلية عن طريق النقر فوق " جربها" .
لسبب ما ، يأخذ swagger اسم الخادم دون منفذ كعنوان URL الأساسي ، لذلك لا تعمل وظيفة Try it out في أمثلة Swagger الخاصة بي. ولكن يمكنك أن تجرب ذلك على التثبيت الخاص بك.
عند النقر فوق Execute Swagger ، ستقوم واجهة المستخدم بإنشاء سلسلة حليقة يمكن استخدامها لتقديم طلب مماثل من سطر الأوامر.

في Swagger UI ، يمكنك حتى إنشاء كائن:



للقيام بذلك ، يكفي أن يكون المستخدم المعتمد لديه الحقوق اللازمة.

ما نراه في هذه الصفحة هو Swagger UI ، وهو مستند تم إنشاؤه استنادًا إلى مواصفات API.

مع وجود اتجاهات في بنية الخدمات المصغرة ، أصبح من المهم بشكل متزايد أن يكون لديك واجهة برمجة تطبيقات موحدة للتفاعل بين المكونات ، حيث من السهل تحديد نقاط النهاية والأساليب لكل من الشخص والتطبيق دون البحث في التعليمات البرمجية المصدر أو وثائق PDF.

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

Swagger هي لغة إطار العمل والمواصفات (التي تمت إعادة تسميتها الآن OpenAPI 2.0) ، مما يسمح لك بتنفيذ هذه المهمة.
لن أتعمق في ذلك.

لمزيد من التفاصيل هنا:



نقد الراحة والبدائل


هناك واحد ، نعم. ليس كل شيء في هذا العالم من عام 2000 وردية بالفعل.

لا أكون خبيراً ، لا أفترض أن أفصح عن الموضوع بشكل كبير ، لكنني سأقدم رابطًا لمقال لا جدال فيه حول هبر .

واجهة بديلة للتفاعل بين مكونات النظام اليوم هو gRPC. كما تنبأ بمستقبل عظيم في مجال الأساليب الجديدة للعمل مع معدات الشبكات. ولكن سنتحدث عنه في وقت ما في المستقبل ، عندما يأتي دوره.

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


مهم
تم استخدام الرمز المميز a9aae70d65c928a554f9a038b9d4703a1583594f لأغراض العرض التوضيحي فقط ولم يعد يعمل.

إشارة مباشرة من الرموز المميزة في رمز البرنامج غير مقبولة ولقد قدمت هنا فقط من أجل تبسيط الأمثلة.


روابط مفيدة



شكرا


  • أندريه بانفيلوف لتصحيح التجارب المطبعية والتحرير
  • الكسندر فاتن لتصحيح التجارب المطبعية والتحرير

Source: https://habr.com/ru/post/ar485618/

More articles:


All Articles