يعد استخدام REST APIs لتوسيع البرامج النصية الخاصة بك ميزة مفيدة للتنفيذ. يمكنك الوصول إلى وظائف جديدة، وتوسيع إمكانيات إنشاء نصوص برمجية جديدة أكثر تقدمًا.
لكن تجربة الكثيرين عند البدء في استخدام REST APIs في البرامج النصية هي أنها تبدو خرقاء وغير طبيعية تمامًا. في هذه التدوينة نناقش:
- ما هي REST API؟
- كيفية قراءة الشكل الأكثر شيوعا من الوثائق
- كيفية استخدام REST API مع PowerShell
- بعض النصائح والحيل حول كيفية جعلها تجربة أسهل وأفضل
ما هو الراحة؟
REST، أو RESTful APIs، هي واجهة برمجة تطبيقات تستخدم طلبات HTTP لجلب البيانات أو إضافتها أو حذفها أو معالجتها في خدمات مختلفة.
ما نريد أن نفعله بالبيانات يتم تحديده عادةً من خلال ماذا طريقة HTTP التي تستخدمها. فيما يلي قائمة مختصرة بطرق HTTP وما يتم استخدامها للقيام به في REST API:
- احصل على — اقرأ
- مشاركة—إنشاء
- التصحيح — التحديث/التعديل الجزئي
- وضع — تحديث/استبدال
- حذف—إزالة
عادةً ما يتم إرجاع البيانات التي يتم إرجاعها بواسطة REST API بتنسيق JSON.
الآن، لنبدأ باستدعاء واجهة برمجة التطبيقات (API) الأول!
قراءة المستندات
يعد تعلم قراءة وتفسير الوثائق الخاصة بواجهات برمجة تطبيقات REST المختلفة أمرًا ضروريًا لاستخدامها. لحسن الحظ، إذا كنت تعرف كيفية قراءة نمط واحد من التوثيق، فيمكنك أن تتعلم بسرعة كيفية قراءة الأنماط الأخرى.
نحن نستخدم petstore.swagger.io في هذه المقالة، لأنه يستخدم شعبية اختيال إطار عمل شائع جدًا في العالم الحقيقي.
توضح الصورة السابقة أهم المعلومات حول نقاط نهاية REST API:
- طريقة HTTP — الحصول/النشر/الحذف، وما إلى ذلك.
- عنوان URL النسبي لنقطة نهاية REST API (عادةً ما يتم عرض عنوان URL الأساسي في أعلى صفحة الوثائق)
- وصف موجز
الدخول في التفاصيل
الصفحة الأولى من الوثائق رائعة، ويمكنك عادةً إجراء معظم الاستدعاءات التي تتطلب طريقة HTTP GET باستخدام تلك المعلومات. لكن أساليب مثل POST وSET تتطلب عادةً النقر فوق الصف وتوسيعه للحصول على مزيد من المعلومات.
إذا قمت بالنقر فوق أحد الصفوف، فسيتم تقديم معلومات تبدو كما يلي:
لقد قدمنا هنا نقطة نهاية REST التي يمكنها إنشاء كائن حيوان أليف جديد. وهو يحدد الشكل الذي يجب أن يبدو عليه ملف JSON الذي تم توفيره في نص POST ونوع المحتوى الذي يقبله. تحدد نقاط نهاية REST الأخرى ما هي المعلمات المختلفة، ونوع البيانات التي ينبغي أن تكون، وما إلى ذلك.
هذه هي أساسيات قراءة الوثائق. الآن أصبح الأمر واضحًا، فقد حان الوقت لبدء استخدام REST APIs مع PowerShell.
احصل على (تينغ) بياناتك الأولى
عادةً ما يكون استخدام واجهات برمجة تطبيقات REST مع PowerShell أمرًا بسيطًا للغاية، وأنت تستخدم أوامر cmdlets المضمنة، لذلك لا حاجة إلى وحدات إضافية. ستقوم بجلب البيانات باستخدام طريقة GET على نقطة النهاية /pet/{petId}.
إذا قمت بتوسيع نقطة النهاية /pet/{petId} في الوثائق، فيمكنك أن ترى أن {petId} هو في الواقع معلمة تأخذ عددًا صحيحًا.
وهذا يجعل عنوان URL لجلب كائن الحيوانات الأليفة بالمعرف 1:
عادةً ما تعرض وثائق SWAGGER REST API عنوان URL الأساسي في أعلى الصفحة.
الآن، لنبدأ مع PowerShell. افتح نافذة Terminal وأدخل:
PS51 > Invoke-RestMethod -Method GET -ContentType "application/json" -Uri ""id : 1
category : @{id=0; name=string}
name : doggie
photoUrls : {string}
tags : {@{id=0; name=string}}
status : available
يقوم Invoc-RestMethod بتحويل JSON الذي تم إرجاعه تلقائيًا إلى كائن، حيث يتم إرجاع نوع المحتوى “application/json” في الاستجابة من الخادم.
Error 404 - Not foundيعني عادةً أنه لا يمكن العثور على الكائن، وليس أن عنوان URL مكتوب بشكل خاطئ.
لقد قمت الآن بنجاح بإجراء أول استدعاء لـ REST API. لكن القدرة على الحصول على البيانات فقط هي أمر مقيد للغاية، لذلك دعونا ننشئ شيئًا باستخدام طريقة POST.
إنشاء كائن باستخدام طريقة POST
يتم استخدام طريقة POST بشكل شائع للإنشاء، مثل إنشاء مستخدمين أو إدخالات، وما إلى ذلك. يرسل طلب POST نصًا يحتوي على معلومات إلى نقطة نهاية REST، عادةً بتنسيق JSON، ولكن يمكن أيضًا أن يكون كنموذج مشفر بعنوان URL.
سوف تتعلم كيفية إنشاء كائن JSON يمكنك نشره إلى نقطة النهاية/pet.
يمكنك أن ترى كيف من المفترض أن يبدو JSON إذا قمت بتوسيع صف POST /pet في الوثائق.
لنبدأ بإنشاء جدول تجزئة يمكننا تحويله لاحقًا إلى كائن JSON. يجب تجنب Raw JSON في البرامج النصية PowerShell لأنها تحد من قدراتها.
$Body = @{
id = 19
category = @{
id = 45
name = "Whatever"
}
name = "Dawg"
photoUrls = @(
"string"
)
tags = @(
@{
id = 0
name = "string"
}
)
status = "available"
} إذا كنت تواجه صعوبة في إنشاء جدول تجزئة يتحول إلى JSON الذي تريده، فقم بتثبيت
بسدكيت
الوحدة النمطية واستخدم الأمر:
$JsonString | ConvertTo-Psd
لديك الآن جدول تجزئة يمكنك تحويله إلى سلسلة JSON وPOST إلى نقطة النهاية/pet:
$JsonBody = $Body | ConvertTo-Json
$Uri = "https://petstore.swagger.io/v2/pet"
Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method Post -Body $JsonBodyid : 19
category : @{id=45; name=Whatever}
name : Dawg
photoUrls : {string}
tags : {@{id=0; name=string}}
status : available
عند إنشاء الكائن، عادةً ما تتلقى الكائن الذي تم إنشاؤه للتأكيد.
باستخدام الحذف
تقوم طريقة DELETE بحذف البيانات، وطريقة القيام بذلك تشبه إلى حد كبير طريقة GET كما هو موضح هنا:
PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "" فقط كن على علم حتى لا تحذف أي شيء قد تحتاجه.
باستخدام وضع
تقوم طريقة PUT بتحديث البيانات الموجودة بالفعل. يتم ذلك بشكل مشابه لطريقة POST، عن طريق إرسال كائن JSON كامل أو جزئي:
PS51> $Body = (PSCustomObject)@{
id = 19
name = "Dawg with a new name"
}PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = "https://petstore.swagger.io/v2/pet"
PS51> Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method PUT -Body $JsonBody
id name photoUrls tags
19 Dawg with a new name {} {}
عادةً ما تقوم REST API بإرجاع كائن JSON مع البيانات المستخدمة و/أو المحدثة. يمكنك أن ترى أنه تم تحديث الكائن باستخدام طريقة GET تجاهه:
PS 51> Invoke-RestMethod -ContentType "application/json" -Uri "9"id : 19
category : @{id=45; name=Whatever}
name : Dawg with a new name
photoUrls : {string}
tags : {@{id=0; name=string}}
status : available
إنشاء الوظائف
قد تصبح كتابة هذه الأوامر كما هي مملة للغاية وغير قابلة للتطوير حقًا. إذا كنا نستدعي نقطة نهاية أكثر من مرة، فقم بإنشاء دالة لها. الأمر بسيط جدًا ولا يلزمك سوى بضعة أسطر:
Function Get-PetstorePet {
(cmdletbinding())
param(
(Parameter(Mandatory,ValueFromPipeline))
(int)$Id
)
Begin{}
Process{
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/$Id"
ContentType = "application/json"
Method = "GET"
}
Invoke-RestMethod @RestMethodParams
}
End{}
} بعد إنشاء وظيفتك، يمكنك استدعاؤها في البرنامج النصي الخاص بك:
PS51> Get-PetstorePet -Id 1id name photoUrls tags
1 Doggie {http://picture.url} {}
يمكنك القيام بذلك من أجل طريقة POST وكذلك لإنشاء حيوان أليف جديد في متجر الحيوانات الأليفة:
Function Add-PetstorePet {
(cmdletbinding())
param(
(Parameter(Mandatory,ValueFromPipelineByPropertyName))
(int)$Id,
(Parameter(Mandatory,ValueFromPipelineByPropertyName))
(string)$Name,
(Parameter(Mandatory,ValueFromPipelineByPropertyName))
(string)$Status,
(Parameter(Mandatory,ValueFromPipelineByPropertyName))
(int)$CategoryId,
(Parameter(Mandatory,ValueFromPipelineByPropertyName))
(string)$CategoryName,
(Parameter(Mandatory,ValueFromPipelineByPropertyName))
(string())$PhotoUrls,
(Parameter(Mandatory,ValueFromPipelineByPropertyName))
(Hashtable())$Tags
)
Begin{}
Process{
$Body = @{
id = $Id
category = @{
id = $CategoryId
name = $CategoryName
}
name = $Name
photoUrls = $PhotoUrls
tags = $Tags
status = $Status
}
$BodyJson = $Body | ConvertTo-Json
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/"
ContentType = "application/json"
Method = "Post"
Body = $BodyJson
}
Invoke-RestMethod @RestMethodParams
}
End{}
} واستدعاء وظيفة PowerShell هذه بعد ذلك يجعل هذه المهمة الطويلة أسهل كثيرًا:
PS51> $AddPetStorePetsParams = @{
Id = 44
Name = "Birdie"
Status = "available"
CategoryId = 50
CategoryName = "Hawks"
PhotoUrls = "https://images.contoso.com/hawk.jpg"
Tags = @(
@{
Id=10
Name="Not eagles"
}
)
}
PS51> Add-PetStorePet @AddPetStorePetsParamsid : 44
category : @{id=50; name=Hawks}
name : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags : {@{id=0}}
status : available
من المحتمل أن العديد من الوحدات التي تستخدمها يوميًا تتكون من وظائف تستخدم واجهات برمجة تطبيقات REST فقط في الخلفية.
ملخص
إن تعلم كيفية استخدام REST APIs يتعلق بشكل أساسي بتعلم قراءة الوثائق. لقد استخدمنا التوثيق المستند إلى SWAGGER في هذا المنشور، لأنه يمثل كيف قد تبدو أنماط التوثيق الأخرى أيضًا.
كما أن تحويل استدعاءات واجهة برمجة التطبيقات (API) الخاصة بك إلى وظيفة يمكن أن يوفر عليك الكثير من الوقت، ويجعل عملك أسهل، ويجعل نصوصك البرمجية أكثر وضوحًا.
(العلامات للترجمة)مايكروسوفت