إضافة واجهة برمجة تطبيقات إلى Azure Static Web Apps باستخدام Azure Functions

مقالة
12/06/2024

يمكنك إضافة واجهات برمجة تطبيقات بلا خادم إلى Azure Static Web Apps مدعومة من Azure Functions. توضح هذه المقالة كيفية إضافة واجهة برمجة تطبيقات ونشرها إلى موقع Azure Static Web Apps.

إشعار

يتم تكوين الوظائف المقدمة افتراضيا في Static Web Apps مسبقا لتوفير نقاط نهاية API آمنة ودعم الوظائف التي يتم تشغيلها بواسطة HTTP فقط. راجع دعم واجهة برمجة التطبيقات مع Azure Functions للحصول على معلومات حول كيفية اختلافها عن تطبيقات Azure Functions المستقلة.

المتطلبات الأساسية

إنشاء حساب في Azure ذي اشتراك نشط.
- إذا لم يكن لديك حساب، يمكنك إنشاء حساب مجانا.
تعليمة Visual Studio البرمجية.
ملحق Azure Static Web Apps ل Visual Studio Code.
ملحق Azure Functions لـ Visual Studio Code.
Node.js v18 لتشغيل تطبيق الواجهة الأمامية وواجهة برمجة التطبيقات.

تلميح

يمكنك استخدام أداة nvm لإدارة إصدارات متعددة من Node.js على نظام التطوير الخاص بك. على Windows، يمكن تثبيت NVM لنظام التشغيل Windows عبر Winget.

إنشاء تطبيق الويب الثابت

قبل إضافة واجهة برمجة تطبيقات، قم بإنشاء ونشر تطبيق واجهة أمامية إلى Azure Static Web Apps باتباع التشغيل السريع إنشاء أول موقع ثابت باستخدام Azure Static Web Apps .

بمجرد نشر تطبيق الواجهة الأمامية في Azure Static Web Apps، قم باستنساخ مستودع التطبيق الخاص بك. على سبيل المثال، يمكنك استنساخ المستودع الخاص بك باستخدام git سطر الأوامر.

قبل تشغيل الأمر التالي، تأكد من استبدال <YOUR_GITHUB_USERNAME> باسم مستخدم GitHub الخاص بك.

git clone https://github.com/<YOUR_GITHUB_USERNAME>/my-first-static-web-app

في Visual Studio Code، افتح جذر مستودع التطبيق الخاص بك. تحتوي بنية المجلد على مصدر تطبيق الواجهة الأمامية وسير عمل GitHub Static Web Apps في مجلد .github/workflows .

├── .github
│   └── workflows
│       └── azure-static-web-apps-<DEFAULT_HOSTNAME>.yml
│
└── (folders and files from your static web app)

إنشاء واجهة برمجة التطبيقات

يمكنك إنشاء مشروع Azure Functions لواجهة برمجة تطبيقات تطبيق الويب الثابت. بشكل افتراضي، ينشئ ملحق Static Web Apps Visual Studio Code المشروع في مجلد يسمى api في جذر المستودع الخاص بك.

اضغط على F1 لفتح لوح الأوامر.
حدد Azure Static Web Apps: Create HTTP Function.... إذا تمت مطالبتك بتثبيت ملحق Azure Functions، فقم بتثبيته وإعادة تشغيل هذا الأمر.

عند المطالبة، أدخل القيم التالية:

المطالبة	القيمة‬
تحديد لغة	JavaScript
تحديد نموذج برمجة	الإصدار 4
منح الدالة اسماً	رسالة

تلميح

يمكنك معرفة المزيد حول الاختلافات بين نماذج البرمجة في دليل مطور Azure Functions

يتم إنشاء مشروع Azure Functions باستخدام دالة مشغلة بواسطة HTTP. يحتوي تطبيقك الآن على بنية مشروع مشابهة للمثال التالي.

├── .github
│   └── workflows
│       └── azure-static-web-apps-<DEFAULT_HOSTNAME>.yml
│
├── api
├── └──src
│   │  │ functions
│   │  │  └── message.js
│   │  └── index.js
│   ├── .funcignore
│   ├── host.json
│   ├── local.settings.json
│   ├── package-lock.json
│   └── package.json
│
└── (...plus other folders and files from your static web app)

بعد ذلك، قم بتغيير الدالة message لإرجاع رسالة إلى الواجهة الأمامية. تحديث الدالة في src/functions/message.js بالتعليمات البرمجية التالية.

const { app } = require('@azure/functions');

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        return { body: `Hello, from the API!` };
    }
});

تلميح

يمكنك إضافة المزيد من وظائف واجهة برمجة التطبيقات عن طريق تشغيل الأمر Azure Static Web Apps: Create HTTP Function... مرة أخرى.

تحديث تطبيق الواجهة الأمامية لاستدعاء واجهة برمجة التطبيقات

قم بتحديث تطبيق الواجهة الأمامية للاتصال بواجهة برمجة التطبيقات في /api/message وعرض رسالة الاستجابة.

إذا استخدمت قوالب التشغيل السريع لإنشاء التطبيق، فاستخدم الإرشادات التالية لتطبيق التحديثات.

قم بتحديث محتوى ملف src/index.html بالتعليمات البرمجية التالية لإحضار النص من دالة API وعرضه على الشاشة.

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="styles.css">
    <title>Vanilla JavaScript App</title>
</head>

<body>
    <main>
    <h1>Vanilla JavaScript App</h1>
    <p>Loading content from the API: <b id="name">...</b></p>
    </main>

    <script>
    (async function() {
        const { text } = await( await fetch(`/api/message`)).json();
        document.querySelector('#name').textContent = text;
    }());
    </script>
</body>

</html>

قم بتحديث محتوى src/app/app.module.ts بالتعليمات البرمجية التالية لتمكينها HttpClient في تطبيقك.

import { BrowserModule } from "@angular/platform-browser";
import { NgModule } from "@angular/core";
import { HttpClientModule } from '@angular/common/http';

import { AppComponent } from "./app.component";

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, HttpClientModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

قم بتحديث محتوى src/app/app.component.ts بالتعليمات البرمجية التالية لإحضار النص من وظيفة واجهة برمجة التطبيقات وعرضه على الشاشة.

import { HttpClient } from '@angular/common/http';
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `<div>{{message}}</div>`,
})
export class AppComponent {
  message = '';

  constructor(private http: HttpClient) {
    this.http.get('/api/message')
      .subscribe((resp: any) => this.message = resp.text);
  }
}

قم بتحديث محتوى src/App.js بالتعليمات البرمجية التالية لإحضار النص من دالة API وعرضه على الشاشة.

import React, { useState, useEffect } from 'react';

function App() {
  const [data, setData] = useState('');

  useEffect(() => {
    (async function () {
      const { text } = await( await fetch(`/api/message`)).json();
      setData(text);
    })();
  });

  return <div>{data}</div>;
}

export default App;

قم بتحديث محتوى src/App.vue بالتعليمات البرمجية التالية لإحضار النص من وظيفة واجهة برمجة التطبيقات وعرضه على الشاشة.

<template>
  <div>{{ message }}</div>
</template>

<script>
export default {
  name: "App",
  data() {
    return {
      message: ""
    };
  },
  async mounted() {
    const { text } = await (await fetch("/api/message")).json();
    this.message = text;
  }
};
</script>

تشغيل الواجهة الأمامية وواجهة برمجة التطبيقات محليا

لتشغيل تطبيق الواجهة الأمامية وواجهة برمجة التطبيقات معا محليا، توفر Azure Static Web Apps CLI الذي يحاكي بيئة السحابة. يستخدم CLI Azure Functions Core Tools لتشغيل واجهة برمجة التطبيقات.

تثبيت أدوات سطر الأوامر

تأكد من تثبيت أدوات سطر الأوامر الضرورية.

هام

لتحسين أمان عمليات النشر من Static Web Apps CLI، تم إدخال تغيير فاصل يتطلب منك الترقية إلى أحدث إصدار (2.0.2) من Static Web Apps CLI بحلول 15 يناير 2025.

npm install -g @azure/static-web-apps-cli

تلميح

إذا كنت لا تريد تثبيت swa سطر الأوامر بشكل عام، يمكنك استخدام npx swa بدلا من swa الإرشادات التالية.

إنشاء تطبيق الواجهة الأمامية

إذا كان تطبيقك يستخدم إطار عمل، فنشئ التطبيق لإنشاء الإخراج قبل تشغيل Static Web Apps CLI.

ليست هناك حاجة لإنشاء التطبيق.

تثبيت تبعيات npm وإنشاء التطبيق في المجلد dist/angular-basic .

npm install
npm run build --prod

تثبيت تبعيات npm وإنشاء التطبيق في مجلد البناء.

npm install
npm run build

تثبيت تبعيات npm وإنشاء التطبيق في مجلد dist .

npm install
npm run build

تشغيل تطبيق ويب محليًا

قم بتشغيل تطبيق الواجهة الأمامية وواجهة برمجة التطبيقات معا عن طريق بدء تشغيل التطبيق باستخدام Static Web Apps CLI. يسمح تشغيل جزأين من التطبيق بهذه الطريقة ل CLI بخدمة إخراج بناء الواجهة الأمامية من مجلد، ويجعل واجهة برمجة التطبيقات قابلة للوصول إلى التطبيق قيد التشغيل.

في جذر المستودع الخاص بك، ابدأ تشغيل Static Web Apps CLI باستخدام start الأمر . اضبط الوسيطات إذا كان تطبيقك يحتوي على بنية مجلد مختلفة.
قم بتمرير المجلد الحالي (src) ومجلد API (api) إلى CLI.
```
swa start src --api-location api
```
مرر مجلد إخراج البنية (dist/angular-basic) ومجلد API (api) إلى CLI.
```
swa start dist/angular-basic --api-location api
```
مرر مجلد إخراج البنية (build) ومجلد API (api) إلى CLI.
```
swa start build --api-location api
```
مرر مجلد إخراج البنية (dist) ومجلد API (api) إلى CLI.
```
swa start dist --api-location api
```
قد يطالب جدار حماية Windows بطلب أن وقت تشغيل Azure Functions يمكنه الوصول إلى الإنترنت. حدد السماح.
عند بدء تشغيل عمليات CLI، قم بالوصول إلى تطبيقك في http://localhost:4280/. لاحظ كيف تستدعي الصفحة واجهة برمجة التطبيقات وتعرض ناتجها، Hello from the API.
لإيقاف CLI، اكتب Ctrl + C.

إضافة موقع واجهة برمجة التطبيقات إلى سير العمل

قبل أن تتمكن من نشر تطبيقك على Azure، قم بتحديث سير عمل GitHub Actions الخاص بالمستودع الخاص بك بالموقع الصحيح لمجلد API الخاص بك.

افتح سير العمل في .github/workflows/azure-static-web-apps-DEFAULT-HOSTNAME<>.yml.

ابحث عن الخاصية api_location وقم بتعيين القيمة إلى api.

###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "src" # App source code path
api_location: "api" # Api source code path - optional
output_location: "" # Built app content directory - optional
###### End of Repository/Build Configurations ######

ملاحظة: القيم أعلاه من api_location ،app_location،output_location هي لأي إطار عمل وتتغير هذه القيم استنادا إلى إطار العمل الخاص بك.

حفظ الملف.

نشر التغييرات

لنشر التغييرات على تطبيق الويب الثابت في Azure، قم بتثبيت التعليمات البرمجية ودفعها إلى مستودع GitHub البعيد.

اضغط على F1 لفتح لوح الأوامر.
حدد الأمر Git: Commit All.
عند مطالبتك برسالة تثبيت، أدخل feat: إضافة API وتثبيت جميع التغييرات في مستودع git المحلي.
اضغط على F1 لفتح لوح الأوامر.
حدد الأمر Git: push.

يتم دفع تغييراتك إلى المستودع البعيد في GitHub، ما يؤدي إلى تشغيل سير عمل Static Web Apps GitHub Actions لإنشاء تطبيقك ونشره.
افتح المستودع الخاص بك في GitHub لمراقبة حالة تشغيل سير العمل الخاص بك.
عند اكتمال تشغيل سير العمل، قم بزيارة تطبيق الويب الثابت لعرض التغييرات.

الخطوات التالية

تكوين إعدادات التطبيق

مشاركة عبر

إضافة واجهة برمجة تطبيقات إلى Azure Static Web Apps باستخدام Azure Functions

المتطلبات الأساسية

إنشاء تطبيق الويب الثابت

إنشاء واجهة برمجة التطبيقات

تحديث تطبيق الواجهة الأمامية لاستدعاء واجهة برمجة التطبيقات

تشغيل الواجهة الأمامية وواجهة برمجة التطبيقات محليا

تثبيت أدوات سطر الأوامر

إنشاء تطبيق الواجهة الأمامية

تشغيل تطبيق ويب محليًا

إضافة موقع واجهة برمجة التطبيقات إلى سير العمل

نشر التغييرات

الخطوات التالية

الملاحظات

الموارد الإضافية