مشغّل HTTP الخاص بدالات Azure

  • مقالة
  • قراءة خلال 23 دقائق

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

القيمة المرجعة الافتراضية لدالة تم تشغيلها في HTTP هي:

  • HTTP 204 No Content مع وجود نص فارغ في دالات 2.x وأعلى
  • HTTP 200 OK مع وجود نص فارغ في دالات 1.x

لتعديل استجابة HTTP، قم بتكوين ربط المخرجات.

لمزيد من المعلومات حول روابط HTTP، راجع نظرة عامة ومرجع ربط المخرجات.

تلميح

إذا كنت تخطط لاستخدام روابط HTTP أو WebHook ، فخطط لتجنب استنفاد المنفذ الذي يمكن أن يحدث بسبب الإنشاء غير السليم ل HttpClient. لمزيد من المعلومات، راجع كيفية إدارة الاتصالات في وظائف Azure.

مثال

يمكن إنشاء الدالة C # باستخدام أحد أوضاع C # التالية:

تعيين التعليمات البرمجية في هذه المقالة افتراضيًا إلى بناء الجملة ‎.NET Core المستخدم في الإصدار 2.x وأعلى من الدالات. للحصول على معلومات حول بناء الجملة 1.x، راجع قوالب الدالات 1.x.

يُظهر المثال التالي دالة C#‎ التي تبحث عن معلمة name إما في سلسلة الاستعلام أو نص طلب HTTP. لاحظ أن القيمة المرجعة تُستخدم لربط المخرجات، ولكن لا يلزم وجود سمة القيمة المرجعة.

[FunctionName("HttpTriggerCSharp")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)]
    HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = String.Empty;
    using (StreamReader streamReader =  new  StreamReader(req.Body))
    {
        requestBody = await streamReader.ReadToEndAsync();
    }
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    return name != null
        ? (ActionResult)new OkObjectResult($"Hello, {name}")
        : new BadRequestObjectResult("Please pass a name on the query string or in the request body");
}

يحتوي هذا القسم على الأمثلة التالية:

تُظهر الأمثلة التالية ربط مشغل HTTP.

قراءة المعلمة من سلسلة الاستعلام

يقرأ هذا المثال معلمة، تسمى id، من سلسلة الاستعلام، ويستخدمها لإنشاء مستند JSON تم إرجاعه إلى العميل، مع نوع المحتوى application/json.

@FunctionName("TriggerStringGet")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", 
            methods = {HttpMethod.GET}, 
            authLevel = AuthorizationLevel.ANONYMOUS)
        HttpRequestMessage<Optional<String>> request,
        final ExecutionContext context) {

    // Item list
    context.getLogger().info("GET parameters are: " + request.getQueryParameters());

    // Get named parameter
    String id = request.getQueryParameters().getOrDefault("id", "");

    // Convert and display
    if (id.isEmpty()) {
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                        .body("Document not found.")
                        .build();
    } 
    else {
        // return JSON from to the client
        // Generate document
        final String name = "fake_name";
        final String jsonDocument = "{\"id\":\"" + id + "\", " + 
                                        "\"description\": \"" + name + "\"}";
        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(jsonDocument)
                        .build();
    }
}

قراءة النص من طلب POST

يقرأ هذا المثال نص طلب POST، تسمى String، من سلسلة الاستعلام، ويستخدمها لإنشاء مستند JSON تم إرجاعه إلى العميل، مع نوع المحتوى application/json.

    @FunctionName("TriggerStringPost")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", 
              methods = {HttpMethod.POST}, 
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Request body is: " + request.getBody().orElse(""));

        // Check request body
        if (!request.getBody().isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        } 
        else {
            // return JSON from to the client
            // Generate document
            final String body = request.getBody().get();
            final String jsonDocument = "{\"id\":\"123456\", " + 
                                         "\"description\": \"" + body + "\"}";
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(jsonDocument)
                          .build();
        }
    }

قراءة المعلمة من مسار

يقرأ هذا المثال معلمة إلزامية، تسمى id، و معلمة اختيارية name من المسار، ويستخدمها لإنشاء مستند JSON تم إرجاعه إلى العميل، مع نوع المحتوى application/json. T

@FunctionName("TriggerStringRoute")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", 
            methods = {HttpMethod.GET}, 
            authLevel = AuthorizationLevel.ANONYMOUS,
            route = "trigger/{id}/{name=EMPTY}") // name is optional and defaults to EMPTY
        HttpRequestMessage<Optional<String>> request,
        @BindingName("id") String id,
        @BindingName("name") String name,
        final ExecutionContext context) {

    // Item list
    context.getLogger().info("Route parameters are: " + id);

    // Convert and display
    if (id == null) {
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                        .body("Document not found.")
                        .build();
    } 
    else {
        // return JSON from to the client
        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " + 
                                        "\"description\": \"" + name + "\"}";
        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(jsonDocument)
                        .build();
    }
}

قراءة نص POJO من طلب POST

فيما يلي التعليمة البرمجية للفئة ToDoItem، المشار إليها في هذا المثال:


public class ToDoItem {

  private String id;
  private String description;  

  public ToDoItem(String id, String description) {
    this.id = id;
    this.description = description;
  }

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

يقرأ هذا المثال نص طلب POST. يتم إلغاء تسلسل نص الطلب تلقائيًا في الكائن ToDoItem، ويتم إرجاعه إلى العميل، مع نوع المحتوى application/json. يتم تسلسل المعلمة ToDoItem بواسطة وقت تشغيل الدالات كما يتم تعيينها إلى الخاصية body للفئة HttpMessageResponse.Builder.

@FunctionName("TriggerPojoPost")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", 
            methods = {HttpMethod.POST}, 
            authLevel = AuthorizationLevel.ANONYMOUS)
        HttpRequestMessage<Optional<ToDoItem>> request,
        final ExecutionContext context) {

    // Item list
    context.getLogger().info("Request body is: " + request.getBody().orElse(null));

    // Check request body
    if (!request.getBody().isPresent()) {
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                        .body("Document not found.")
                        .build();
    } 
    else {
        // return JSON from to the client
        // Generate document
        final ToDoItem body = request.getBody().get();
        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(body)
                        .build();
    }
}

يُظهر المثال التالي ربط مشغل في ملف function.json وملف دالة JavaScript التي تستخدم الربط. تبحث الدالة عن معلمة name إما في سلسلة الاستعلام أو نص طلب HTTP.

إليك ملف function.json:

{
    "disabled": false,    
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req"
        },
        {
            "type": "http",
            "direction": "out",
            "name": "res"
        }
    ]
}

قسم التكوين يشرح هذه الخصائص.

هنا رمز JavaScript:

module.exports = async function(context, req) {
    context.log('Node.js HTTP trigger function processed a request. RequestUri=%s', req.originalUrl);

    if (req.query.name || (req.body && req.body.name)) {
        context.res = {
            // status defaults to 200 */
            body: "Hello " + (req.query.name || req.body.name)
        };
    }
    else {
        context.res = {
            status: 400,
            body: "Please pass a name on the query string or in the request body"
        };
    }
};

يُظهر المثال التالي ربط مشغل في ملف function.js ودالة PowerShell. تبحث الدالة عن معلمة name إما في سلسلة الاستعلام أو نص طلب HTTP.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$name = $Request.Query.Name
if (-not $name) {
    $name = $Request.Body.Name
}

$body = "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."

if ($name) {
    $body = "Hello, $name. This HTTP triggered function executed successfully."
}

# Associate values to output bindings by calling 'Push-OutputBinding'.
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body       = $body
})

يُظهر المثال التالي ربط مشغل في ملف function.json ودالة Python التي تستخدم الربط. تبحث الدالة عن معلمة name إما في سلسلة الاستعلام أو نص طلب HTTP.

إليك ملف function.json:

{
    "scriptFile": "__init__.py",
    "disabled": false,    
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req"
        },
        {
            "type": "http",
            "direction": "out",
            "name": "$return"
        }
    ]
}

قسم التكوين يشرح هذه الخصائص.

فيما يلي التعليمة البرمجية لـ Python:

import logging
import azure.functions as func


def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

    name = req.params.get('name')
    if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

    if name:
        return func.HttpResponse(f"Hello {name}!")
    else:
        return func.HttpResponse(
            "Please pass a name on the query string or in the request body",
            status_code=400
        )

السمات

تستخدم كل من مكتبات C#‎ للعملية قيد المعالجة والعملية المعزولةHttpTriggerAttribute تعريف ربط المشغل. يستخدم البرنامج النصي C # بدلا من ذلك ملف تكوين function.json.

في الدالات أثناء العملية ، HttpTriggerAttribute يدعم المعلمات التالية:

المعلمات الوصف
AuthLevel تحديد المفاتيح، إن وجدت، التي يجب أن تكون موجودة عند الطلب لاستدعاء الدالة. للاطلاع على القيم المدعومة، راجع مستوى التفويض.
الأساليب صفيف من أساليب HTTP التي تستجيب لها الدالة. في حالة عدم التحديد، تستجيب الدالة لكافة أساليب HTTP. راجع تخصيص نقطة نهاية HTTP.
المسار تحديد قالب المسار، الذي يتحكم في عناوين URLs للطلب التي تستجيب الدالة الخاص بك إليها. القيمة الافتراضية إذا لم يتم توفير أي شيء هي <functionname>. لمزيد من المعلومات، راجع تخصيص نقطة نهاية HTTP.
WebHookType معتمدة فقط لوقت تشغيل الإصدار 1.x.

تكوين مشغل HTTP ليكون بمثابة مستقبل إخطار على الويب للموفر المحدد. للاطلاع على القيم المدعومة، راجع نوع WebHook.

تعليقات توضيحية

في مكتبة وقت تشغيل وظائف Java، استخدم التعليق التوضيحي HttpTrigger ، الذي يدعم الإعدادات التالية:

تهيئة

يشرح الجدول التالي خصائص تكوين المشغل التي قمت بتعيينها في الملف function.json ، والتي تختلف حسب إصدار وقت التشغيل.

يشرح الجدول الآتي خصائص تكوين ربط البيانات التي عليك تعيينها في ملف function.json.

خاصية function.json الوصف
النوع مطلوب - يجب تعيينه إلى httpTrigger.
الاتجاه مطلوب - يجب تعيينه إلى in.
الاسم مطلوب - اسم المتغير المستخدم في التعليمات البرمجية للدالة للطلب أو نص الطلب.
authLevel تحديد المفاتيح، إن وجدت، التي يجب أن تكون موجودة عند الطلب لاستدعاء الدالة. للاطلاع على القيم المدعومة، راجع مستوى التفويض.
الأساليب صفيف من أساليب HTTP التي تستجيب لها الدالة. في حالة عدم التحديد، تستجيب الدالة لكافة أساليب HTTP. راجع تخصيص نقطة نهاية HTTP.
المسار تحديد قالب المسار، الذي يتحكم في عناوين URLs للطلب التي تستجيب الدالة الخاص بك إليها. القيمة الافتراضية إذا لم يتم توفير أي شيء هي <functionname>. لمزيد من المعلومات، راجع تخصيص نقطة نهاية HTTP.

الاستخدام

يوضح هذا القسم بالتفصيل كيفية تكوين ربط وظيفة مشغل HTTP.

يجب تطبيق التعليق التوضيحي HttpTrigger على معلمة أسلوب من أحد الأنواع التالية:

  • httpRequestMessage< ر>.
  • أي أنواع جافا أصلية مثل int و String و byte [].
  • قيم قابلة للإلغاء باستخدام اختياري.
  • أي نوع كائن Java قديم عادي (POJO).

البيانات الأساسية

يتم تعريف نوع إدخال المشغل إما كنوع مخصص أو HttpRequest. إذا اخترت HttpRequest، يمكنك الحصول على حق الوصول الكامل إلى كائن الطلب. بالنسبة لنوع مخصص، يحاول وقت التشغيل تحليل نص طلب JSON لتعيين خصائص الكائن.

تخصيص نقطة نهاية HTTP

بشكل افتراضي، عند إنشاء دالة مشغل HTTP، تكون الدالة قابلة للعنونة من خلال مسار النموذج:

http://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>

يمكنك تخصيص هذا المسار باستخدام خاصية route الاختيارية على ربط الإدخال الخاص بمشغل HTTP. يمكنك استخدام أي قيد من قيود مسار واجهة برمجة تطبيقات الويب مع المعلمات الخاصة بك.

يقبل رمز الدالة C # التالي معلمتين categoryid وفي المسار ويكتب استجابة باستخدام كلا المعلمتين.

[FunctionName("Function1")]
public static IActionResult Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "products/{category:alpha}/{id:int?}")] HttpRequest req,
string category, int? id, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var message = String.Format($"Category: {category}, ID: {id}");
    return (ActionResult)new OkObjectResult(message);
}

يتم تعريف معلمات المسار باستخدام route إعداد التعليق التوضيحي HttpTrigger . يقبل رمز الدالة التالي معلمتين categoryid وفي المسار ويكتب استجابة باستخدام كلا المعلمتين.

package com.function;

import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerJava {
    public HttpResponseMessage<String> HttpTrigger(
            @HttpTrigger(name = "req",
                         methods = {"get"},
                         authLevel = AuthorizationLevel.FUNCTION,
                         route = "products/{category:alpha}/{id:int}") HttpRequestMessage<String> request,
            @BindingName("category") String category,
            @BindingName("id") int id,
            final ExecutionContext context) {

        String message = String.format("Category  %s, ID: %d", category, id);
        return request.createResponseBuilder(HttpStatus.OK).body(message).build();
    }
}

على سبيل المثال، يعرف ملف function.json التالي خاصية route لمشغلات HTTP بمعلمتين، category و id:

{
    "bindings": [
    {
        "type": "httpTrigger",
        "name": "req",
        "direction": "in",
        "methods": [ "get" ],
        "route": "products/{category:alpha}/{id:int?}"
    },
    {
        "type": "http",
        "name": "res",
        "direction": "out"
    }
    ]
}

يوفر وقت تشغيل الدالات نص الطلب من context الكائن. يوضح المثال التالي كيفية قراءة معلمات المسار من context.bindingData.

module.exports = async function (context, req) {

    var category = context.bindingData.category;
    var id = context.bindingData.id;
    var message = `Category: ${category}, ID: ${id}`;

    context.res = {
        body: message;
    }
}

يمكن الوصول إلى معلمات المسار التي يتم الإعلان عنها في ملف function.json كخاصية للكائن $Request.Params.

$Category = $Request.Params.category
$Id = $Request.Params.id

$Message = "Category:" + $Category + ", ID: " + $Id

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body = $Message
})

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

بمجرد تعريفها، تتوفر معلمات المسار للدالة عن طريق استدعاء الأسلوب route_params.

import logging

import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:

    category = req.route_params.get('category')
    id = req.route_params.get('id')
    message = f"Category: {category}, ID: {id}"

    return func.HttpResponse(message)

باستخدام هذا التكوين، تكون الدالة الآن قابلة للعنونة من خلال المسار التالي بدلاً من المسار الأصلي.

http://<APP_NAME>.azurewebsites.net/api/products/electronics/357

يتيح هذا التكوين للتعليمات البرمجية للدالة دعم معلمتين في العنوان، الفئةوالمعرّف. لمزيد من المعلومات حول كيفية ترميز معلمات المسار في عنوان URL، راجع التوجيه في ASP.NET Core.

بشكل افتراضي، يتم بدء كافة مسارات الدالة من خلال api. يمكنك أيضًا تخصيص أو إزالة البادئة باستخدام الخاصية extensions.http.routePrefix في ملف host.js. يقوم المثال التالي بإزالة بادئة مسار api باستخدام سلسلة فارغة للبادئة في ملف host.js.

{
    "extensions": {
        "http": {
            "routePrefix": ""
        }
    }
}

استخدام معلمات المسار

معلمات المسار التي حددت نمط دالة route متوفرة لكل ربط. على سبيل المثال، إذا كان لديك مسار محدد باسم "route": "products/{id}" فإنه يمكن لربط تخزين جدول استخدام قيمة المعلمة {id} في تكوين الربط.

يُظهر التكوين التالي كيفية تمرير المعلمة {id} إلى rowKey الخاص بالربط.

{
    "type": "table",
    "direction": "in",
    "name": "product",
    "partitionKey": "products",
    "tableName": "products",
    "rowKey": "{id}"
}

عند استخدام معلمات المسار، يتم إنشاء invoke_URL_template تلقائيًا للدالة الخاصة بك. يمكن للعملاء لديك استخدام قالب عنوان URL لفهم المعلمات التي يحتاجون إلى تمريرها في عنوان URL عند استدعاء الدالة باستخدام عنوان URL الخاص بها. انتقل إلى إحدى الدالات التي تم تشغيلها في HTTP في مدخل Azure وحدد الحصول على عنوان URL للدالة.

يمكنك الوصول برمجيًا إلى invoke_URL_template باستخدام واجهات برمجة تطبيقات Azure Resource Manager لدالات القائمة أو الحصول على دالة.

العمل مع هويات العميل

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

يمكنك أيضًا قراءة هذه المعلومات من بيانات الربط. تتوفر هذه الإمكانية فقط لوقت تشغيل الدالات في 2.x وأعلى. كما أنها متوفرة حاليًا فقط للغات ‎.NET.

تتوفر المعلومات المتعلقة بالعملاء المصادق عليهم كمطالبات رئيسية ، والتي تتوفر كجزء من سياق الطلب كما هو موضح في المثال التالي:

using System.Net;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;

public static IActionResult Run(HttpRequest req, ILogger log)
{
    ClaimsPrincipal identities = req.HttpContext.User;
    // ...
    return new OkObjectResult();
}

بدلاً من ذلك، يمكن ببساطة إدراج ClaimsPrincipal كمعلمة إضافية في توقيع الدالة:

using System.Net;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;
using Newtonsoft.Json.Linq;

public static void Run(JObject input, ClaimsPrincipal principal, ILogger log)
{
    // ...
    return;
}

المستخدم المصادق عليه متوفر عبر عناوين HTTP.

مستوى التخويل

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

قيمة المستوى الوصف
مجهول لا يوجد مفتاح API مطلوب.
دالة مفتاح API الخاص بالدالة مطلوب. هذه هي القيمة الافتراضية عندما لا يتم تعيين مستوى على وجه التحديد.
المشرف المفتاح الرئيسي مطلوب.

مفاتيح وصول وظيفية

تتيح لك الوظائف استخدام المفاتيح لتسهيل الوصول إلى نقاط نهاية وظيفة HTTP أثناء التطوير. ما لم يتم تعيين مستوى الوصول إلى HTTP على وظيفة تشغيل HTTP إلى anonymous، يجب أن تتضمن الطلبات مفتاح وصول API في الطلب.

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

عند تجديد قيم مفتاح الدالة، يجب إعادة توزيع قيم المفاتيح المحدثة يدويا على كافة العملاء الذين يستدعون الدالة.

نطاقات التفويض (على مستوى الوظيفة)

هناك نطاقان للوصول إلى المفاتيح على مستوى الوظيفة:

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

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

يتم تسمية كل مفتاح كمرجع، وهناك مفتاح افتراضي (يسمى "افتراضي") على مستوى الوظيفة والمضيف. مفاتيح الوظائف لها الأسبقية على مفاتيح المضيف. عندما يتم تعريف مفتاحين بنفس الاسم، يتم استخدام مفتاح الوظيفة دائما.

المفتاح الرئيسي (على مستوى المسؤول)

يحتوي كل تطبيق وظيفة أيضا على مفتاح مضيف على مستوى المسؤول يسمى _master. بالإضافة إلى توفير الوصول على مستوى المضيف إلى جميع الوظائف في التطبيق ، يوفر المفتاح الرئيسي أيضا وصولا إداريا إلى واجهات برمجة تطبيقات REST لوقت التشغيل. لا يمكن إبطال هذا المفتاح. عند تعيين مستوى adminوصول ، يجب أن تستخدم الطلبات المفتاح الرئيسي ؛ أي مفتاح آخر يؤدي إلى فشل الوصول.

تنبيه

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

الحصول على المفاتيح

يتم تخزين المفاتيح كجزء من تطبيق الدالة في Azure ويتم تشفيرها في حالة الراحة. لعرض المفاتيح أو إنشاء مفاتيح جديدة أو نقل المفاتيح إلى قيم جديدة، انتقل إلى إحدى الدالات التي تم تشغيلها في HTTP في مدخل Azure وحدد مفاتيح الدالات.

يمكنك أيضًا إدارة مفاتيح المضيف. انتقل إلى تطبيق الدالة في مدخل Azure وحدد مفاتيح التطبيق.

يمكنك الحصول على مفاتيح الدالة والمضيف برمجيًا باستخدام واجهات برمجة تطبيقات Azure Resource Manager. هناك واجهات برمجة التطبيقات إلى مفاتيح دالة القائمة ومفاتيح مضيف القائمة، وعند استخدام فتحات النشر، تكون واجهات برمجة التطبيقات المكافئة هي فتحة مفاتيح دالة القائمة وفتحة مفاتيح مضيف القائمة.

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

يمكن حذف مفاتيح الدالة والمضيف برمجيًا باستخدام واجهات برمجة التطبيقات حذف سر الدالة وحذف فتحة سر الدالة وحذف سر المضيف وحذف فتحة سر المضيف.

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

تخويل مفتاح API

تتطلب معظم قوالب مشغل HTTP مفتاح API في الطلب. لذا يبدو طلب HTTP الخاص بك عادة مثل عنوان URL التالي:

https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?code=<API_KEY>

يمكن تضمين المفتاح في متغير سلسلة استعلام مسمى code، كما هو مذكور أعلاه. ويمكن أيضًا تضمينه في عنوان HTTP x-functions-key. يمكن أن تكون قيمة المفتاح عبارة عن أي مفتاح دالة معرّف للدالة أو أي مفتاح مضيف.

يمكنك السماح بطلبات مجهولة المصدر، والتي لا تتطلب مفاتيح. يمكنك أيضًا طلب استخدام المفتاح الرئيسي. تغيّر مستوى التخويل الافتراضي باستخدام الخاصية authLevel في JSON الربط. لمزيد من المعلومات، راجع المشغل- التكوين.

ملاحظة

عند تشغيل الدالات محليًا، يتم تعطيل التخويل بغض النظر عن إعداد مستوى التخويل المحدد. بعد النشر إلى Azure، يتم فرض الإعداد authLevel في المشغل. لا تزال المفاتيح مطلوبة عند تشغيل محليًا في حاوية.

تأمين نقطة نهاية HTTP في الإنتاج

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

تمكين مصادقة/تخويل خدمة التطبيق

يتيح لك النظام الأساسي لخدمة التطبيقات استخدام Azure Active Directory (AAD (دليل Azure النشط)) والعديد من موفري الهوية التابعين لجهات خارجية لمصادقة العملاء. يمكنك استخدام هذه الاستراتيجية لتنفيذ قواعد التخويل المخصصة لوظائفك، ويمكنك العمل مع معلومات المستخدم من التعليمات البرمجية للوظيفة. لمعرفة المزيد، راجع المصادقة والتخويل في خدمة تطبيقات Azureوالعمل مع هويات العملاء.

استخدام إدارة واجهة برمجة تطبيقات Azure (APIM) لمصادقة الطلبات

توفر APIM مجموعة متنوعة من خيارات أمان واجهة برمجة التطبيقات للطلبات الواردة. لمعرفة المزيد، راجع سياسات مصادقة إدارة واجهة برمجة التطبيقات. مع وجود APIM في مكانه، يمكنك تكوين تطبيق الوظائف الخاص بك لقبول الطلبات فقط من عنوان IP الخاص بمثيل APIM الخاص بك. لمعرفة المزيد، راجع قيود عنوان IP.

نشر تطبيق وظيفتك بمعزل عن غيره

توفر بيئة خدمة تطبيقات Azure (ASE) بيئة استضافة مخصصة لتشغيل وظائفك. تتيح لك بورصة عمان تكوين بوابة أمامية واحدة يمكنك استخدامها لمصادقة جميع الطلبات الواردة. لمزيد من المعلومات، راجع تكوين جدار حماية تطبيق ويب (WAF) لبيئة خدمة التطبيق.

خطافات الويب

ملاحظة

وضع إخطار على الويب متوفر فقط للإصدار 1.x من وقت تشغيل الدالات. تم إجراء هذا التغيير لتحسين أداء مشغلات HTTP في الإصدار 2.x وأعلى.

في الإصدار 1.x، توفر قوالب الإخطارات على الويب التحقق من الصحة الإضافي للبيانات الأساسية للإخطار على الويب. في الإصدار 2.x وأعلى، لا يزال مشغل HTTP الأساسي يعمل وهو النهج الموصى به للإخطارات على الويب.

نوع ويب هوك

webHookType تشير خاصية الربط إلى نوع إذا كان webhook مدعوما بالوظيفة، والتي تملي أيضا الحمولة المدعومة. يمكن أن يكون نوع إخطار على الويب إحدى القيم التالية:

قيمة النوع الوصف
جينيريكجسون نقطة نهاية إخطار على الويب للأغراض العامة بدون منطق لموفر معين. يقيد هذا الإعداد الطلبات لأولئك الذين يستخدمون HTTP POST فقط ومع نوع المحتوى application/json.
جيثب تستجيب الدالة إلى إخطارات GitHub على الويب. لا تستخدم authLevel الموقع مع GitHub الويب.
الركود تستجيب الدالة إلى إخطارات Slack على الويب. لا تستخدم authLevel مكان الإقامة مع خطافات الويب Slack .

عند تعيين webHookType الخاصية، لا تقم أيضا بتعيين methods الخاصية على الربط.

إخطارات GitHub على الويب

للاستجابة إلى إخطارات GitHub على الويب، يمكنك أولاً إنشاء الدالة الخاصة بك مع مشغل HTTP، وتعيين الخاصية webHookType إلى github. ثم انسخ عنوان URL ومفتاح API الخاصين بها إلى صفحة إضافة إخطار على الويب في مستودع GitHub.

Screenshot that shows how to add a webhook for your function.

إخطارات Slack على الويب

ينشئ إخطار Slack على الويب رمزًا مميزًا بدلاً من السماح لك بتحديده، لذا يتعين عليك تكوين مفتاح خاص بالدالة مع الرمز المميز من Slack. انظر مفاتيح التخويل.

الإخطارات على الويب والمفاتيح

تتم معالجة تخويل إخطار على الويب بواسطة مكون مستقبل إخطار على الويب وجزء من مشغل HTTP وتختلف الآلية استنادًا إلى نوع إخطار على الويب. تعتمد كل آلية على مفتاح. بشكل افتراضي، يتم استخدام مفتاح الدالة المسمى "افتراضي". لاستخدام مفتاح مختلف، يمكنك تكوين موفر إخطار على الويب لإرسال اسم المفتاح مع الطلب بإحدى الطرق التالية:

  • سلسلة الاستعلام: يقوم الموفر بتمرير اسم المفتاح في معلمة سلسلة استعلامclientid، مثل https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.
  • عنوان الطلب: يقوم الموفر بتمرير اسم المفتاح في عنوان x-functions-clientid.

أنواع المحتوى

يتطلب تمرير البيانات الثنائية وبيانات النموذج إلى دالة غير C#‎ استخدام عنوان نوع المحتوى المناسب. تتضمن أنواع المحتويات المعتمدة octet-stream للبيانات الثنائية وأنواع الأجزاء المتعددة.

المشاكل المعروفة

في الدالات غير C#‎، تؤدي الطلبات المرسلة مع نوع المحتوى image/jpeg إلى قيمة string يتم تمريرها إلى الدالة. في مثل هذه الحالات، يمكنك تحويل القيمة string يدويًا إلى صفيف بايت للوصول إلى البيانات الثنائية الأولية.

الحدود

يقتصر طول طلب HTTP على 100 ميغابايت (104,857,600 بايت)، ويقتصر طول URL على 4 كيلوبايت (4096 بايت). يتم تحديد هذه الحدود بواسطة عنصر httpRuntime لملف Web.config الخاص بوقت التشغيل.

إذا لم تكتمل دالة تستخدم مشغل HTTP خلال 230 ثانية، فإن مهلة Azure Load Balancer ستنقضي وتُرجع خطأ HTTP 502. سوف تستمر الدالة في التشغيل ولكنها لن تتمكن من إرجاع استجابة HTTP. بالنسبة للدالات طويلة الأمد، نوصي باتباع أنماط غير متزامنة وإرجاع موقع حيث يمكنك اختبار الاتصال لحالة الطلب. للحصول على معلومات حول المدة التي يمكن تشغيل الدالة خلالها، راجع تغيير السعة والاستضافة - خطة الاستهلاك.

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