Sdílet prostřednictvím

Příručka pro vývojáře Azure Functions Node.js

Tato příručka představuje úvod do vývoje Azure Functions pomocí JavaScriptu nebo TypeScriptu. Článek předpokládá, že už jste si přečetli příručku pro vývojáře Azure Functions.

Důležité

Obsah tohoto článku se změní na základě vašeho výběru programovacího modelu Node.js v selektoru v horní části této stránky. Verze, kterou zvolíte, by se měla shodovat s verzí @azure/functions balíčku npm, který používáte ve své aplikaci. Pokud tento balíček ve vašem package.jsonseznamu nemáte, výchozí hodnota je v3. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Jako vývojář Node.js vás může zajímat také jeden z následujících článků:

Začínáme Koncepty Výuka s vedením

Úvahy

  • Programovací model Node.js by se neměl zaměňovat s modulem runtime Azure Functions:
    • Programovací model: Definuje způsob vytváření kódu a je specifický pro JavaScript a TypeScript.
    • Runtime: Definuje základní chování Azure Functions a sdílí se napříč všemi jazyky.
  • Verze programovacího modelu je přísně svázaná s verzí @azure/functions balíčku npm. Verze je nezávislá na modulu runtime. Modul runtime i programovací model používají číslo 4 jako nejnovější hlavní verzi, ale to je náhoda.
  • Programovací modely v3 a v4 nemůžete kombinovat ve stejné aplikaci funkcí. Jakmile ve své aplikaci zaregistrujete jednu funkci v4, budou všechny funkce v3 zaregistrované v function.json souborech ignorovány.

Podporované verze

Následující tabulka uvádí každou verzi programovacího modelu Node.js spolu s podporovanými verzemi modulu runtime Azure Functions a Node.js.

Verze programovacího modelu Úroveň podpory Verze modulu runtime služby Functions verze Node.js Popis
4.x GA 4.25+ 22.x 20.x, 18.x Podporuje flexibilní strukturu souborů a přístup orientovaný na kód pro triggery a vazby.
3.x GA 4.x 20.x, 18.x, 16.x, 14.x Vyžaduje konkrétní strukturu souborů s triggery a vazbami deklarovanými v souboru "function.json".
2.x Není k dispozici 3.x 14.x, 12.x, 10.x Podpora skončila 13. prosince 2022. Další informace najdete v tématu Verze služby Functions.
1.x Není k dispozici 2.x 10.x, 8.x Podpora skončila 13. prosince 2022. Další informace najdete v tématu Verze služby Functions.

Struktura složek

Požadovaná struktura složek pro projekt JavaScriptu vypadá jako v následujícím příkladu:

<project_root>/
 | - .vscode/
 | - node_modules/
 | - myFirstFunction/
 | | - index.js
 | | - function.json
 | - mySecondFunction/
 | | - index.js
 | | - function.json
 | - .funcignore
 | - host.json
 | - local.settings.json
 | - package.json

Hlavní složka projektu, <project_root>, může obsahovat následující soubory:

  • .vscode/: (volitelné) Obsahuje uloženou konfiguraci Visual Studio Code. Další informace najdete v tématu nastavení Visual Studio Code.
  • myFirstFunction/function.json: Obsahuje konfiguraci pro aktivační událost, vstupy a výstupy funkce. Název adresáře určuje název vaší funkce.
  • myFirstFunction/index.js: Ukládá kód funkce. Pokud chcete změnit tuto výchozí cestu k souboru, podívejte se na použití scriptFile.
  • .funcignore: (Volitelné) Deklaruje soubory, které by se neměly publikovat do Azure. Tento soubor obvykle obsahuje soubor .vscode/ pro ignorování nastavení editoru, testování/ ignorování testovacích případů a local.settings.json , aby se zabránilo publikování nastavení místní aplikace.
  • host.json: Obsahuje možnosti konfigurace, které ovlivňují všechny funkce v instanci aplikace funkcí. Tento soubor se publikuje do Azure. Při místním spuštění nejsou všechny možnosti podporovány. Další informace najdete v tématu host.json.
  • local.settings.json: Slouží k ukládání nastavení aplikací a připojovacích řetězců při místním spuštění aplikace. Tento soubor se nepublikuje do Azure. Další informace najdete v souboru local.settings.file.
  • package.json: Obsahuje možnosti konfigurace, jako je seznam závislostí balíčků, hlavní vstupní bod a skripty.

Doporučená struktura složek pro projekt JavaScriptu vypadá jako v následujícím příkladu:

<project_root>/
 | - .vscode/
 | - node_modules/
 | - src/
 | | - functions/
 | | | - myFirstFunction.js
 | | | - mySecondFunction.js
 | - test/
 | | - functions/
 | | | - myFirstFunction.test.js
 | | | - mySecondFunction.test.js
 | - .funcignore
 | - host.json
 | - local.settings.json
 | - package.json

Hlavní složka projektu, <project_root>, může obsahovat následující soubory:

  • .vscode/: (volitelné) Obsahuje uloženou konfiguraci Visual Studio Code. Další informace najdete v tématu nastavení Visual Studio Code.
  • src/functions/: Výchozí umístění pro všechny funkce a související triggery a vazby.
  • test/: (Volitelné) Obsahuje testovací případy vaší aplikace funkcí.
  • .funcignore: (Volitelné) Deklaruje soubory, které by se neměly publikovat do Azure. Tento soubor obvykle obsahuje soubor .vscode/ pro ignorování nastavení editoru, testování/ ignorování testovacích případů a local.settings.json , aby se zabránilo publikování nastavení místní aplikace.
  • host.json: Obsahuje možnosti konfigurace, které ovlivňují všechny funkce v instanci aplikace funkcí. Tento soubor se publikuje do Azure. Při místním spuštění nejsou všechny možnosti podporovány. Další informace najdete v tématu host.json.
  • local.settings.json: Slouží k ukládání nastavení aplikací a připojovacích řetězců při místním spuštění aplikace. Tento soubor se nepublikuje do Azure. Další informace najdete v souboru local.settings.file.
  • package.json: Obsahuje možnosti konfigurace, jako je seznam závislostí balíčků, hlavní vstupní bod a skripty.

Registrace funkce

Model v3 zaregistruje funkci na základě existence dvou souborů. Nejprve potřebujete function.json soubor umístěný ve složce o jednu úroveň dolů od kořenového adresáře aplikace. Zadruhé potřebujete javascriptový soubor, který exportuje vaši funkci. Ve výchozím nastavení model hledá index.js soubor ve stejné složce jako vaše function.json. Pokud používáte TypeScript, musíte použít vlastnost scriptFile v function.json k odkazování na zkompilovaný JavaScriptový soubor. Pokud chcete přizpůsobit umístění souboru nebo název exportu funkce, podívejte se na konfiguraci vstupního bodu vaší funkce.

Funkce, kterou exportujete, by měla být vždy deklarována jako v async function modelu v3. Synchronní funkci můžete exportovat, ale pak musíte volat context.done() jako signál, že funkce byla dokončena, což je zastaralé a nedoporučuje se.

Funkci se předá volání funkcecontext jako první argument a vaše vstupy jako zbývající argumenty.

Následující příklad představuje jednoduchou funkci, která zaznamenává, že byla spuštěna, a reaguje s Hello, world!.

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "authLevel": "anonymous",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

module.exports = async function (context, request) {
  context.log("Http function was triggered.");
  context.res = { body: "Hello, world!" };
};

Programovací model načítá vaše funkce na základě pole main ve vašem package.json. Pole můžete nastavit main na jeden soubor nebo více souborů pomocí glob patternu. Následující tabulka ukazuje ukázkové hodnoty pro main pole:

Příklad Popis
src/index.js Zaregistrujte funkce z jednoho kořenového souboru.
src/functions/*.js Zaregistrujte každou funkci z vlastního souboru.
src/{index.js,functions/*.js} Kombinace, kde každou funkci zaregistrujete z vlastního souboru, ale stále máte kořenový soubor pro obecný kód na úrovni aplikace.

Chcete-li zaregistrovat funkci, musíte importovat app objekt z @azure/functions modulu npm a volat metodu specifickou pro váš typ triggeru. Prvním argumentem při registraci funkce je název funkce. Druhým argumentem options je objekt určující konfiguraci pro trigger, obslužnou rutinu a všechny další vstupy nebo výstupy. V některých případech, kdy není konfigurace triggeru nutná, můžete obslužnou rutinu předat přímo jako druhý argument místo objektu options .

Registraci funkce je možné provést z libovolného souboru v projektu, pokud je tento soubor načten (přímo nebo nepřímo) na základě pole main v souboru package.json. Funkce by měla být zaregistrována v globálním oboru, protože po spuštění nelze zaregistrovat funkce.

Následující příklad představuje jednoduchou funkci, která zaznamenává, že byla spuštěna, a reaguje s Hello, world!.

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

app.http("helloWorld1", {
  methods: ["POST", "GET"],
  handler: async (request, context) => {
    context.log("Http function was triggered.");
    return { body: "Hello, world!" };
  },
});

Vstupy a výstupy

Vaše funkce musí mít přesně jeden primární vstup, který se nazývá trigger. Může mít také sekundární vstupy nebo výstupy. Vstupy a výstupy se konfigurují ve vašich function.json souborech a označují se také jako vazby.

Vstupy

Vstupy jsou vazby, které mají direction nastavený na in. Hlavní rozdíl mezi triggerem a sekundárním vstupem je v tom, že pro trigger končí type, například typ Trigger vs typ blobTrigger. Většina funkcí používá pouze aktivační událost a nepodporuje se mnoho sekundárních vstupních typů.

Ke vstupům je možné přistupovat několika způsoby:

  • [Doporučeno] Jako argumenty předané funkci: Použijte argumenty ve stejném pořadí, v jakém jsou definovány .function.json Vlastnost name definovaná v function.json něm se nemusí shodovat s názvem argumentu, i když ji doporučujeme pro účely organizace.

    module.exports = async function (context, myTrigger, myInput, myOtherInput) { ... };

  • Jako vlastnosti context.bindings: Použijte klíč odpovídající name vlastnosti definované v function.json.

    module.exports = async function (context) {
  context.log("This is myTrigger: " + context.bindings.myTrigger);
  context.log("This is myInput: " + context.bindings.myInput);
  context.log("This is myOtherInput: " + context.bindings.myOtherInput);
};

Výstupy

Výstupy jsou vazby, kde je direction nastaveno na out, a lze je určit několika způsoby:

  • [Doporučeno pro jeden výstup] Vrátí hodnotu přímo: Pokud používáte asynchronní funkci, můžete ji vrátit přímo. V name je potřeba změnit vlastnost výstupní vazby na $return, aby byla function.json jako v následujícím příkladu:

    {
  "name": "$return",
  "type": "http",
  "direction": "out"
}

    module.exports = async function (context, request) {
  return {
    body: "Hello, world!",
  };
};

  • [Doporučeno pro více výstupů] Vrátí objekt obsahující všechny výstupy: Pokud používáte asynchronní funkci, můžete vrátit objekt s vlastností odpovídající názvu každé vazby ve vaší function.json. Následující příklad používá výstupní vazby s názvem httpResponse a queueOutput:

    {
    "name": "httpResponse",
    "type": "http",
    "direction": "out"
},
{
    "name": "queueOutput",
    "type": "queue",
    "direction": "out",
    "queueName": "helloworldqueue",
    "connection": "storage_APPSETTING"
}

    module.exports = async function (context, request) {
  let message = "Hello, world!";
  return {
    httpResponse: {
      body: message,
    },
    queueOutput: message,
  };
};

  • Nastavte hodnoty na context.bindings: Pokud nepoužíváte asynchronní funkci nebo nechcete používat předchozí možnosti, můžete hodnoty nastavit přímo na context.bindingsmísto, kde klíč odpovídá názvu vazby. Následující příklad používá výstupní vazby s názvem httpResponse a queueOutput:

    {
    "name": "httpResponse",
    "type": "http",
    "direction": "out"
},
{
    "name": "queueOutput",
    "type": "queue",
    "direction": "out",
    "queueName": "helloworldqueue",
    "connection": "storage_APPSETTING"
}

    module.exports = async function (context, request) {
  let message = "Hello, world!";
  context.bindings.httpResponse = {
    body: message,
  };
  context.bindings.queueOutput = message;
};

Datový typ vazby

Vlastnost vstupní vazby dataType můžete použít ke změně typu vstupu. Přístup má ale určitá omezení:

  • V Node.js jsou podporovány pouze string a binary podporované (stream není)
  • U vstupů dataType HTTP je vlastnost ignorována. Místo toho použijte vlastnosti objektu request k získání textu v požadovaném formátu. Další informace najdete v požadavku HTTP.

V následujícím příkladu triggeru fronty úložiště je výchozím typem myQueueItem, ale pokud nastavíte stringdataType , typ se změní na Node.js binary.Buffer

{
  "name": "myQueueItem",
  "type": "queueTrigger",
  "direction": "in",
  "queueName": "helloworldqueue",
  "connection": "storage_APPSETTING",
  "dataType": "binary"
}

const { Buffer } = require("node:buffer");

module.exports = async function (context, myQueueItem) {
  if (typeof myQueueItem === "string") {
    context.log("myQueueItem is a string");
  } else if (Buffer.isBuffer(myQueueItem)) {
    context.log("myQueueItem is a buffer");
  }
};

Vaše funkce musí mít přesně jeden primární vstup, který se nazývá trigger. Může mít také sekundární vstupy, primární výstup označovaný jako návratový výstup nebo sekundární výstupy. Vstupy a výstupy se také označují jako vazby mimo kontext programovacího modelu Node.js. Před verzí 4 modelu byly tyto vazby nakonfigurovány v function.json souborech.

Vstup triggeru

Aktivační událost je jediným požadovaným vstupem nebo výstupem. U většiny typů triggerů zaregistrujete funkci pomocí metody u objektu app pojmenovaného po typu triggeru. Můžete zadat konfiguraci specifickou pro trigger přímo v argumentu options . Například trigger HTTP umožňuje zadat trasu. Během provádění je hodnota související s touto spouštěcí událostí předána jako první argument vašemu obslužnému modulu.

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

app.http('helloWorld1', {
    route: 'hello/world',
    handler: async (request, context) => {
        ...
    }
});

Návratový výstup

Návratový výstup je volitelný a v některých případech je ve výchozím nastavení nakonfigurovaný. Například trigger HTTP zaregistrovaný pomocí app.http je nakonfigurovaný tak, aby automaticky vrátil výstup odpovědi HTTP. U většiny výstupních typů zadáte návratovou konfiguraci options argumentu pomocí objektu output exportovaného z @azure/functions modulu. Během provádění nastavíte tento výstup tak, že ho vrátíte z obslužné rutiny.

Následující příklad používá trigger časovače a výstup fronty úložiště:

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

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.storageQueue({
        connection: 'storage_APPSETTING',
        ...
    }),
    handler: (myTimer, context) => {
        return { hello: 'world' }
    }
});

Další vstupy a výstupy

Kromě triggeru a návratu můžete při registraci funkce zadat další vstupy nebo výstupy options argumentu. Objekty input a output exportované z modulu @azure/functions poskytují metody specifické pro typ, které pomáhají konstruovat konfiguraci. Během provádění získáte nebo nastavíte hodnoty s původním konfiguračním objektem context.extraInputs.get nebo context.extraOutputs.set, předáním původního objektu konfigurace jako prvního argumentu.

Následující příklad je funkce aktivovaná frontou úložiště , s dodatečným vstupem objektu blob úložiště, který je zkopírován do dodatečného výstupu objektu blob úložiště. Zpráva ve frontě by měla obsahovat název souboru a nahradí {queueTrigger} jako název objektu blob, který se má zkopírovat, pomocí vazbového výrazu .

const { app, input, output } = require("@azure/functions");

const blobInput = input.storageBlob({
  connection: "storage_APPSETTING",
  path: "helloworld/{queueTrigger}",
});

const blobOutput = output.storageBlob({
  connection: "storage_APPSETTING",
  path: "helloworld/{queueTrigger}-copy",
});

app.storageQueue("copyBlob1", {
  queueName: "copyblobqueue",
  connection: "storage_APPSETTING",
  extraInputs: [blobInput],
  extraOutputs: [blobOutput],
  handler: (queueItem, context) => {
    const blobInputValue = context.extraInputs.get(blobInput);
    context.extraOutputs.set(blobOutput, blobInputValue);
  },
});

Obecné vstupy a výstupy

Objekty app, trigger, input a output exportované modulem @azure/functions poskytují metody specifické pro většinu typů. Pro všechny typy, které nejsou podporovány, je k dispozici metoda, generic která vám umožní ručně zadat konfiguraci. Metodu generic lze použít také v případě, že chcete změnit výchozí nastavení poskytovaná metodou specifickou pro konkrétní typ.

Následující příklad je jednoduchá funkce aktivovaná protokolem HTTP, která místo metod specifických pro typ používá obecné metody.

const { app, output, trigger } = require("@azure/functions");

app.generic("helloWorld1", {
  trigger: trigger.generic({
    type: "httpTrigger",
    methods: ["GET", "POST"],
  }),
  return: output.generic({
    type: "http",
  }),
  handler: async (request, context) => {
    context.log(`Http function processed request for url "${request.url}"`);

    return { body: `Hello, world!` };
  },
});

Typů SDK

Několik rozšíření vazeb teď umožňuje pracovat přímo s typy Azure SDK.

Azure Blob Storage

Funkce vazeb sady SDK v Azure Functions umožňuje pracovat přímo s typy sady SDK Azure Blob Storage, jako jsou BlobClient a ContainerClient místo nezpracovaných dat. To poskytuje úplný přístup ke všem metodám sady SDK při práci s objekty blob.

Konfigurace projektu pro práci s typy sad SDK:

  1. Přidejte do souboru v projektu balíčky preview rozšíření @azure/functions-extensions-blob, které by měly obsahovat alespoň tyto balíčky: package.json
"dependencies": {
  "@azure/functions": "4.7.2-preview",
  "@azure/functions-extensions-blob": "0.2.0-preview"
},
  1. Přidejte enableHttpStream: true do app.setup pro podporu typů streamování:
import { app } from '@azure/functions';

app.setup({
    enableHttpStream: true,
});

Tento příklad ukazuje, jak získat Objekt BlobClient z triggeru objektu blob služby Storage i ze vstupní vazby triggeru HTTP:

import "@azure/functions-extensions-blob"; // This is the mandatory first import for SDK binding
import { StorageBlobClient } from "@azure/functions-extensions-blob";
import { app, InvocationContext } from "@azure/functions";

export async function storageBlobTrigger(
  blobStorageClient: StorageBlobClient, // SDK binding provides this client
  context: InvocationContext
): Promise<void> {
  context.log(`Blob trigger processing: ${context.triggerMetadata.name}`);

  // Access to full SDK capabilities
  const blobProperties = await blobStorageClient.blobClient.getProperties();
  context.log(`Blob size: ${blobProperties.contentLength}`);

  // Download blob content
  const downloadResponse = await blobStorageClient.blobClient.download();
  context.log(`Content: ${downloadResponse}`);
}

// Register the function
app.storageBlob("storageBlobTrigger", {
  path: "snippets/{name}",
  connection: "AzureWebJobsStorage",
  sdkBinding: true, // Enable SDK binding
  handler: storageBlobTrigger,
});

Tento příklad ukazuje, jak získat ContainerClient prostřednictvím vstupní vazby objektu blob služby Storage s použitím HTTP triggeru:

import "@azure/functions-extensions-blob"; // This is the mandatory first import for SDK binding
import { StorageBlobClient } from "@azure/functions-extensions-blob";
import {
  app,
  HttpRequest,
  HttpResponseInit,
  input,
  InvocationContext,
} from "@azure/functions";

const blobInput = input.storageBlob({
  path: "snippets",
  connection: "AzureWebJobsStorage",
  sdkBinding: true,
});

export async function listBlobs(
  request: HttpRequest,
  context: InvocationContext
): Promise<HttpResponseInit> {
  // Get input binding for a specific container
  const storageBlobClient = context.extraInputs.get(
    blobInput
  ) as StorageBlobClient;

  // List all blobs in the container
  const blobs = [];
  for await (const blob of storageBlobClient.containerClient.listBlobsFlat()) {
    blobs.push(blob.name);
  }

  return { jsonBody: { blobs } };
}

app.http("listBlobs", {
  methods: ["GET"],
  authLevel: "function",
  extraInputs: [blobInput],
  handler: listBlobs,
});

Při práci s typy sad SDK mějte na paměti tyto aspekty:

  • Vždy mějte import "@azure/functions-extensions-blob" na začátku svých souborů, abyste zajistili spuštění vedlejších efektů.
  • Nastavení sdkBinding: true v konfiguraci vazby.
  • Pro vaši operaci použijte odpovídající typ klienta:
    • blobClient pro operace na jednom blobu
    • containerClient pro operace v kontejneru
  • Odpovídající zpracování chyb pomocí try/catch bloků
  • U velkých operací s objekty blob zvažte použití metod streamování, abyste se vyhnuli problémům s pamětí.

Další informace získáte z těchto příkladů použití vazeb sady SDK Blob Storage pro Node.js: další příklady, jak začlenit vazby sady SDK pro Blob do vaší funkční aplikace.

Azure Service Bus

Tento příklad používá typ sady SDK ServiceBusReceivedMessage získané z ServiceBusMessageContext poskytnuté triggerem Service Bus:

import '@azure/functions-extensions-servicebus'; // Ensure the Service Bus extension is imported
import { app, InvocationContext } from '@azure/functions';
import { ServiceBusMessageContext, messageBodyAsJson } from '@azure/functions-extensions-servicebus';

// This sample uses sdkBinding = true with manual message completion.
// With v0.4.0, message.body is returned as a raw Buffer instead of auto-parsed object.
export async function serviceBusQueueTrigger(
    serviceBusMessageContext: ServiceBusMessageContext,
    context: InvocationContext
): Promise<void> {
    const message = serviceBusMessageContext.messages[0];

    // v0.4.0: message.body is a Buffer — use messageBodyAsJson<T>() from the extension for one-line parsing
    const bodyData = messageBodyAsJson(message);
    context.log('Parsed message body:', bodyData);

    // Get current retry count from custom properties, default to 0
    const currentRetryCount = message.applicationProperties?.retryCnt
        ? parseInt(message.applicationProperties.retryCnt as string)
        : 0;
    context.log(`Current retry count: ${currentRetryCount}`);

    if (currentRetryCount >= 3) {
        // After 3 retries, complete the message to remove it from the queue
        context.log(`Maximum retry count (3) reached. Completing message to prevent infinite loop.`);
        await serviceBusMessageContext.actions.complete(message);
        context.log('Message completed after maximum retries');
    } else {
        // Abandon with updated retry count
        const newRetryCount = currentRetryCount + 1;
        const propertiesToModify = {
            retryCnt: newRetryCount.toString(),
            lastRetryTime: new Date().toISOString(),
            errorMessage: 'Processing failed',
        };

        context.log(`Abandoning message with retry count: ${newRetryCount}`);
        await serviceBusMessageContext.actions.abandon(message, propertiesToModify);
    }

    context.log('triggerMetadata: ', context.triggerMetadata);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'ServiceBusConnection',
    queueName: 'testqueue',
    sdkBinding: true,

Další příklad použití typů SDK sady najdete v ukázce strategie exponenciálního zpomalování.

Kontext vyvolání

Každé vyvolání funkce se předává objekt vyvolání context , který se používá ke čtení vstupů, nastavení výstupů, zápisu do protokolů a čtení různých metadat. V modelu v3 je kontextový objekt vždy prvním argumentem předaným obslužné funkci.

Objekt context má následující vlastnosti:

Vlastnost Popis
invocationId ID aktuálního volání funkce.
executionContext Viz kontext spuštění.
bindings Viz vazby.
bindingData Metadata o vstupu triggeru pro toto vyvolání, nikoli zahrnutí samotné hodnoty. Například trigger centra událostí má enqueuedTimeUtc vlastnost.
traceContext Kontext distribuovaného trasování. Další informace najdete na webu Trace Context.
bindingDefinitions Konfigurace vašich vstupů a výstupů, jak je definováno v function.json.
req Viz požadavek HTTP.
res Viz odpověď HTTP.

kontext.výkonovýKontext

Objekt context.executionContext má následující vlastnosti:

Vlastnost Popis
invocationId ID aktuálního volání funkce.
functionName Název funkce, která je vyvolávána. Název složky obsahující function.json soubor určuje název funkce.
functionDirectory Složka obsahující function.json soubor.
retryContext Viz kontext opakování.

context.executionContext.retryContext

Objekt context.executionContext.retryContext má následující vlastnosti:

Vlastnost Popis
retryCount Číslo představující aktuální pokus o opakování.
maxRetryCount Maximální počet opakování provádění Hodnota -1 znamená pokus opakovatelný do nekonečna.
exception Výjimka, která způsobila opakování

kontext.přiřazení

Objekt context.bindings se používá ke čtení vstupů nebo nastavení výstupů. Následující příklad je spouštěčem fronty úložiště, který používá context.bindings ke zkopírování blobu úložiště jako vstupu do blobu úložiště jako výstupu. Obsah zprávy fronty nahradí {queueTrigger} jako název souboru, který se má zkopírovat, pomocí výrazu pro sestavení vazby.

{
    "name": "myQueueItem",
    "type": "queueTrigger",
    "direction": "in",
    "connection": "storage_APPSETTING",
    "queueName": "helloworldqueue"
},
{
    "name": "myInput",
    "type": "blob",
    "direction": "in",
    "connection": "storage_APPSETTING",
    "path": "helloworld/{queueTrigger}"
},
{
    "name": "myOutput",
    "type": "blob",
    "direction": "out",
    "connection": "storage_APPSETTING",
    "path": "helloworld/{queueTrigger}-copy"
}

module.exports = async function (context, myQueueItem) {
  const blobValue = context.bindings.myInput;
  context.bindings.myOutput = blobValue;
};

kontext.hotovo

Metoda context.done je zastaralá. Před podporou asynchronních funkcí byste signalizovali, že se funkce provádí voláním context.done():

module.exports = function (context, request) {
  context.log("this pattern is now deprecated");
  context.done();
};

Doporučujeme odebrat volání context.done() a označit funkci jako asynchronní, aby vrátila příslib (i když nic ne await ). Jakmile se vaše funkce dokončí (jinými slovy, vrácený slib se splní), model v3 ví, že je vaše funkce hotová.

module.exports = async function (context, request) {
  context.log("you don't need context.done or an awaited call");
};

Každému vyvolání vaší funkce je předán objekt vyvolání context s informacemi o daném vyvolání a metodách použité k protokolování. V modelu v4 je objekt context obvykle druhým argumentem předaným obslužné rutině.

Třída InvocationContext má následující vlastnosti:

Vlastnost Popis
invocationId ID aktuálního volání funkce.
functionName Název funkce.
extraInputs Slouží k získání hodnot dodatečných vstupů. Další informace najdete v dalších vstupech a výstupech.
extraOutputs Slouží k nastavení hodnot extra výstupů. Další informace najdete v dalších vstupech a výstupech.
retryContext Viz kontext opakování.
traceContext Kontext distribuovaného trasování. Další informace najdete na webu Trace Context.
triggerMetadata Metadata o vstupu triggeru pro toto vyvolání, nikoli zahrnutí samotné hodnoty. Například trigger centra událostí má enqueuedTimeUtc vlastnost.
options Možnosti použité při registraci funkce, po jejich ověření a s explicitně zadanými výchozími hodnotami.

Kontext opakování

Objekt retryContext má následující vlastnosti:

Vlastnost Popis
retryCount Číslo představující aktuální pokus o opakování.
maxRetryCount Maximální počet opakování provádění Hodnota -1 znamená pokus opakovatelný do nekonečna.
exception Výjimka, která způsobila opakování

Další informace najdete na webu retry-policies.

Protokolování

V Azure Functions se doporučuje k zápisu protokolů použít context.log(). Azure Functions se integruje se službou Azure Application Insights, abyste mohli lépe zaznamenávat protokoly aplikace funkcí. Application Insights, která je součástí Azure Monitor, poskytuje zařízení pro shromažďování, vizuální vykreslování a analýzu protokolů aplikací i výstupů trasování. Další informace najdete v tématu monitorování Azure Functions.

Poznámka:

Pokud použijete alternativní Node.js console.log metodu, tyto protokoly se sledují na úrovni aplikace a nebudou přidruženy k žádné konkrétní funkci. Důrazně doporučujeme, abyste pro protokolování používali context místo console, aby byly všechny protokoly spojeny s konkrétní funkcí.

Následující příklad zapíše protokol na výchozí úroveň "information", včetně ID vyvolání:

context.log(`Something has happened. Invocation ID: "${context.invocationId}"`);

Úrovně protokolování

Kromě výchozí context.log metody jsou k dispozici následující metody, které umožňují psát protokoly na konkrétních úrovních:

metoda Popis
context.log.error() Zapíše do protokolů událost na úrovni chyby.
context.log.warn() Zapíše do protokolů událost na úrovni upozornění.
context.log.info() Zapíše do protokolů událost na úrovni informací.
context.log.verbose() Zapíše do protokolů událost na úrovni trasování.
metoda Popis
context.trace() Zapíše do protokolů událost na úrovni trasování.
context.debug() Zapíše událost úrovně ladění do protokolů.
context.info() Zapíše do protokolů událost na úrovni informací.
context.warn() Zapíše do protokolů událost na úrovni upozornění.
context.error() Zapíše do protokolů událost na úrovni chyby.

Nastavit úroveň protokolu

Azure Functions umožňuje definovat prahovou úroveň, která se má použít při sledování a prohlížení protokolů. K nastavení prahové hodnoty použijte logging.logLevel vlastnost v host.json souboru. Tato vlastnost umožňuje definovat výchozí úroveň použitou pro všechny funkce nebo prahovou hodnotu pro každou jednotlivou funkci. Další informace najdete v tématu Jak nakonfigurovat monitorování pro Azure Functions.

Sledování vlastních dat

Ve výchozím nastavení Azure Functions zapisuje výstup ve formě trasování do Application Insights. Pokud chcete mít větší kontrolu, můžete místo toho použít sadu Application Insights Node.js SDK k odesílání vlastních protokolů, metrik a závislostí do instance Application Insights.

Poznámka:

Metody v sadě Application Insights Node.js SDK se můžou v průběhu času měnit. V příkladech uvedených tady můžou být menší rozdíly v syntaxi. Nejnovější příklady použití rozhraní API najdete v dokumentaci k sadě Application Insights Node.js SDK.

Pro distribuované trasování v programovacím modelu Node.js v4 můžete místo sady Application Insights SDK použít @azure/functions-opentelemetry-instrumentation balíček. Tento balíček poskytuje automatickou instrumentaci založenou na OpenTelemetry pro Azure Functions. Další informace najdete v OpenTelemetry Azure Functions Instrumentation for Node.js GitHub repository.

const appInsights = require("applicationinsights");
appInsights.setup();
const client = appInsights.defaultClient;

module.exports = async function (context, request) {
  // Use this with 'tagOverrides' to correlate custom logs to the parent function invocation.
  var operationIdOverride = {
    "ai.operation.id": context.traceContext.traceparent,
  };

  client.trackEvent({
    name: "my custom event",
    tagOverrides: operationIdOverride,
    properties: { customProperty2: "custom property value" },
  });
  client.trackException({
    exception: new Error("handled exceptions can be logged with this method"),
    tagOverrides: operationIdOverride,
  });
  client.trackMetric({
    name: "custom metric",
    value: 3,
    tagOverrides: operationIdOverride,
  });
  client.trackTrace({
    message: "trace message",
    tagOverrides: operationIdOverride,
  });
  client.trackDependency({
    target: "http://dbname",
    name: "select customers proc",
    data: "SELECT * FROM Customers",
    duration: 231,
    resultCode: 0,
    success: true,
    dependencyTypeName: "ZSQL",
    tagOverrides: operationIdOverride,
  });
  client.trackRequest({
    name: "GET /customers",
    url: "http://myserver/customers",
    duration: 309,
    resultCode: 200,
    success: true,
    tagOverrides: operationIdOverride,
  });
};

Parametr tagOverrides nastaví operation_Id na ID vyvolání funkce. Toto nastavení umožňuje korelovat všechny automaticky generované a vlastní protokoly pro vyvolání dané funkce.

HTTP spouštěče

Triggery HTTP a webhooku používají objekty požadavků a odpovědí k reprezentaci zpráv HTTP.

Triggery HTTP a webhooku používají HttpRequest a HttpResponse objekty k reprezentaci zpráv HTTP. Třídy představují podmnožinu standardu 'fetch', používající balíček Node.jsundici.

Požadavek HTTP

K žádosti je možné získat přístup několika způsoby:

  • Jako druhý argument funkce:

    module.exports = async function (context, request) {
    context.log(`Http function processed request for url "${request.url}"`);

  • Z vlastnosti context.req:

    module.exports = async function (context, request) {
    context.log(`Http function processed request for url "${context.req.url}"`);

  • Z pojmenovaných vstupních vazeb: Tato možnost funguje stejně jako všechny vazby jiné než HTTP. Název function.json vazby musí odpovídat klíči na context.bindings nebo "request1" v následujícím příkladu:

    {
  "name": "request1",
  "type": "httpTrigger",
  "direction": "in",
  "authLevel": "anonymous",
  "methods": ["get", "post"]
}

    module.exports = async function (context, request) {
    context.log(`Http function processed request for url "${context.bindings.request1.url}"`);

Objekt HttpRequest má následující vlastnosti:

Vlastnost Typ Popis
method string Metoda požadavku HTTP použitá k vyvolání této funkce.
url string Adresa URL požadavku.
headers Record<string, string> Hlavičky požadavku HTTP. U tohoto objektu se rozlišují malá a velká písmena. Místo toho se doporučuje používat request.getHeader('header-name') nerozlišující velká a malá písmena.
query Record<string, string> Zadejte dotaz na klíče parametrů řetězce a hodnoty z adresy URL.
params Record<string, string> Klíče a hodnoty parametrů trasy.
user HttpRequestUser \| null Objekt představující přihlášeného uživatele, a to buď prostřednictvím ověřování funkcí, ověřování SWA nebo null, pokud se takový uživatel nepřihlašuje.
body Buffer \| string \| any Pokud je typ média "application/octet-stream" nebo "multipart/*", body je buffer. Pokud je hodnota řetězec podporující parsování JSON, body jedná se o parsovaný objekt. body Jinak je to řetězec.
rawBody string Tělo jako řetězec. Navzdory názvu tato vlastnost nevrací Buffer.
bufferBody Buffer Tělo jako vyrovnávací paměť.

Požadavek může být přístupný jako první argument obslužné rutiny pro funkci aktivovanou protokolem HTTP.

async (request, context) => {
    context.log(`Http function processed request for url "${request.url}"`);

Objekt HttpRequest má následující vlastnosti:

Vlastnost Typ Popis
method string Metoda požadavku HTTP použitá k vyvolání této funkce.
url string Adresa URL požadavku.
headers Headers Hlavičky požadavku HTTP.
query URLSearchParams Zadejte dotaz na klíče parametrů řetězce a hodnoty z adresy URL.
params Record<string, string> Klíče a hodnoty parametrů trasy.
user HttpRequestUser \| null Objekt představující přihlášeného uživatele, a to buď prostřednictvím ověřování funkcí, ověřování SWA nebo null, pokud se takový uživatel nepřihlašuje.
body ReadableStream \| null Tělo jako čitelný datový proud
bodyUsed boolean Logická hodnota označující, jestli je tělo již přečtené.

Pro přístup k textu požadavku nebo odpovědi je možné použít následující metody:

metoda Návratový typ
arrayBuffer() Promise<ArrayBuffer>
blob() Promise<Blob>
formData() Promise<FormData>
json() Promise<unknown>
text() Promise<string>

Poznámka:

Funkce těla lze spustit pouze jednou. Následná volání se vyřeší s prázdnými řetězci nebo ArrayBuffers.

Odpověď protokolu HTTP

Odpověď lze nastavit několika způsoby:

  • context.res Nastavte vlastnost:

    module.exports = async function (context, request) {
    context.res = { body: `Hello, world!` };

  • Vraťte odpověď: Pokud je vaše funkce asynchronní a nastavíte název $return vazby ve vaší function.json, můžete odpověď vrátit přímo, místo toho, abyste ji nastavili v context.

    {
  "type": "http",
  "direction": "out",
  "name": "$return"
}

    module.exports = async function (context, request) {
    return { body: `Hello, world!` };

  • Nastavte pojmenovanou výstupní vazbu: Tato možnost funguje stejně jako všechny vazby jiného typu než HTTP. Název function.json vazby musí odpovídat klíči na context.bindingsnebo "response1" v následujícím příkladu:

    {
  "type": "http",
  "direction": "out",
  "name": "response1"
}

    module.exports = async function (context, request) {
    context.bindings.response1 = { body: `Hello, world!` };

  • Volání context.res.send(): Tato možnost je zastaralá. Implicitně volá context.done() a nedá se použít v asynchronní funkci.

    module.exports = function (context, request) {
    context.res.send(`Hello, world!`);

Pokud při nastavování odpovědi vytvoříte nový objekt, musí tento objekt odpovídat HttpResponseSimple rozhraní, které má následující vlastnosti:

Vlastnost Typ Popis
headers Record<string, string> (volitelné) Hlavičky odpovědi HTTP.
cookies Cookie[] (volitelné) Soubory cookie odpovědi HTTP.
body any (volitelné) Text odpovědi HTTP.
statusCode number (volitelné) Stavový kód odpovědi HTTP. Pokud není nastavená, výchozí hodnota 200je .
status number (volitelné) Totéž jako statusCode. Tato vlastnost je ignorována, pokud statusCode je nastavena.

Objekt context.res můžete také upravit bez přepsání. Výchozí context.res objekt používá HttpResponseFull rozhraní, které podporuje následující metody kromě HttpResponseSimple vlastností:

metoda Popis
status() Nastaví stav.
setHeader() Nastaví pole záhlaví. POZNÁMKA: res.set() a res.header() jsou také podporovány a dělají totéž.
getHeader() Získejte pole záhlaví. POZNÁMKA: res.get() Je také podporován a dělá totéž.
removeHeader() Odebere záhlaví.
type() Nastaví hlavičku content-type.
send() Tato metoda je zastaralá. Nastaví tělo a zavolá context.done() k označení dokončení synchronizační funkce. POZNÁMKA: res.end() Je také podporován a dělá totéž.
sendStatus() Tato metoda je zastaralá. Nastaví stavový kód a volání context.done() , která označují dokončení synchronizační funkce.
json() Tato metoda je zastaralá. Nastaví "content-type" na "application/json", nastaví obsah a volá context.done(), čímž označí, že synchronizační funkce je dokončena.

Odpověď lze nastavit několika způsoby:

  • Jako jednoduché rozhraní s typem HttpResponseInit: Tato možnost je nejvýstižnější způsob vrácení odpovědí.

    return { body: `Hello, world!` };

Rozhraní HttpResponseInit má následující vlastnosti:

Vlastnost Typ Popis
body BodyInit (volitelné) Text odpovědi HTTP jako jeden z ArrayBuffer, AsyncIterable<Uint8Array>, BlobFormDataIterable<Uint8Array>NodeJS.ArrayBufferViewURLSearchParams, null, nebo .string
jsonBody any (volitelné) Text odpovědi HTTP, který lze serializovat do formátu JSON. Pokud je nastavena, HttpResponseInit.body vlastnost je ignorována ve prospěch této vlastnosti.
status number (volitelné) Stavový kód odpovědi HTTP. Pokud není nastavená, výchozí hodnota 200je .
headers HeadersInit (volitelné) Hlavičky odpovědi HTTP.
cookies Cookie[] (volitelné) Soubory cookie odpovědi HTTP.

  • Jako třída s typem HttpResponse: Tato možnost poskytuje pomocné metody pro čtení a úpravy různých částí odpovědi, jako jsou hlavičky.

    const response = new HttpResponse({ body: `Hello, world!` });
response.headers.set("content-type", "application/json");
return response;

Třída HttpResponse přijímá volitelný HttpResponseInit argument jako argument jeho konstruktoru a má následující vlastnosti:

Vlastnost Typ Popis
status number Stavový kód odpovědi HTTP.
headers Headers Hlavičky odpovědi HTTP.
cookies Cookie[] Soubory cookie odpovědi HTTP.
body ReadableStream | null Tělo jako čitelný datový proud
bodyUsed boolean Boolean označující, zda bylo tělo již přečteno.

Streamy HTTP

Streamy HTTP jsou funkce, která usnadňuje zpracování velkých dat, streamování odpovědí OpenAI, doručování dynamického obsahu a podporu dalších základních scénářů HTTP. Umožňuje streamovat požadavky a odpovědi z koncových bodů HTTP v rámci vaší funkční aplikace Node.js. Streamy HTTP používejte ve scénářích, kdy vaše aplikace vyžaduje výměnu v reálném čase a interakci mezi klientem a serverem přes PROTOKOL HTTP. Streamy HTTP můžete použít také k zajištění nejlepšího výkonu a spolehlivosti vašich aplikací při používání protokolu HTTP.

Důležité

Streamy HTTP nejsou v modelu v3 podporované. Upgradujte na model verze 4 a použijte funkci streamování HTTP. Existující HttpRequest a HttpResponse typy v programovacím modelu v4 již podporují různé způsoby zpracování textu zprávy, včetně datového proudu.

Požadavky

Povolení datových proudů

Pomocí těchto kroků povolíte streamy HTTP v aplikaci funkcí v Azure a v místních projektech:

  1. Pokud plánujete streamovat velké objemy dat, upravte nastavení FUNCTIONS_REQUEST_BODY_SIZE_LIMIT v Azure. Výchozí maximální povolená velikost těla je 104857600, což omezuje vaše požadavky na velikost ~100 MB.

  2. Pro místní vývoj přidejte FUNCTIONS_REQUEST_BODY_SIZE_LIMIT také do souboru local.settings.json.

  3. Do libovolného souboru, který je součástí hlavního pole, přidejte do aplikace následující kód.

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

app.setup({ enableHttpStream: true });

Příklady streamů

Tento příklad ukazuje funkci aktivovanou protokolem HTTP, která přijímá data prostřednictvím požadavku HTTP POST, a funkce streamuje tato data do zadaného výstupního souboru:

const { app } = require('@azure/functions');
const { createWriteStream } = require('fs');
const { Writable } = require('stream');

app.http('httpTriggerStreamRequest', {
    methods: ['POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        const writeStream = createWriteStream('<output file path>');
        await request.body.pipeTo(Writable.toWeb(writeStream));

        return { body: 'Done!' };
    },
});

Tento příklad ukazuje funkci aktivovanou protokolem HTTP, která streamuje obsah souboru jako odpověď na příchozí požadavky HTTP GET:

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

app.http('httpTriggerStreamResponse', {
    methods: ['GET'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        const body = createReadStream('<input file path>');

        return { body };
    },
});

Pokud chcete ukázkovou aplikaci připravenou ke spuštění pomocí datových proudů, podívejte se na tento příklad na GitHub.

Aspekty datových proudů

  • Použijte request.body k získání maximálního užitku z používání proudů. Stále můžete používat metody, jako je request.text(), které vždy vrací tělo jako řetězec.

Háčky

Háky nejsou v modelu v3 podporované. Upgradujte na model v4, abyste mohli používat háky.

Pomocí háku můžete spustit kód v různých bodech životního cyklu Azure Functions. Háky se spouštějí v pořadí, ve kterém jsou zaregistrované, a dají se zaregistrovat z libovolného souboru ve vaší aplikaci. V současné době existují dva rozsahy háku, úroveň aplikace a úroveň vyvolání.

Zavolací háky

Volací háky jsou spuštěny jednou při každém vyvolání funkce, buď před ní v háku preInvocation, nebo po ní v háku postInvocation. Ve výchozím nastavení se váš hook spustí pro všechny typy aktivačních událostí, ale můžete také filtrovat podle typu. Následující příklad ukazuje, jak zaregistrovat invokaci hooku a filtrovat podle typu spouštěče.

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

app.hook.preInvocation((context) => {
    if (context.invocationContext.options.trigger.type === 'httpTrigger') {
        context.invocationContext.log(
            `preInvocation hook executed for http function ${context.invocationContext.functionName}`
        );
    }
});

app.hook.postInvocation((context) => {
    if (context.invocationContext.options.trigger.type === 'httpTrigger') {
        context.invocationContext.log(
            `postInvocation hook executed for http function ${context.invocationContext.functionName}`
        );
    }
});

Prvním argumentem obslužné rutiny háku je kontextový objekt specifický pro daný typ háku.

Objekt PreInvocationContext má následující vlastnosti:

Vlastnost Popis
inputs Argumenty předané k volání.
functionHandler Obslužná rutina pro vyvolání funkce. Změny této hodnoty ovlivňují samotnou funkci.
invocationContext Objekt vyvolání kontextu předaný funkci.
hookData Doporučené místo pro ukládání a sdílení dat mezi hooky ve stejném rozsahu. Měli byste použít jedinečný název vlastnosti, aby nebyl v konfliktu s daty jiných háků.

Objekt PostInvocationContext má následující vlastnosti:

Vlastnost Popis
inputs Argumenty předané k volání.
result Výsledek funkce. Změny této hodnoty ovlivňují celkový výsledek funkce.
error Chyba vyvolaná funkcí, nebo null/undefined, pokud neexistuje žádná chyba. Změny této hodnoty ovlivňují celkový výsledek funkce.
invocationContext Objekt vyvolání kontextu předaný funkci.
hookData Doporučené místo pro ukládání a sdílení dat mezi hooky ve stejném rozsahu. Měli byste použít jedinečný název vlastnosti, aby nebyl v konfliktu s daty jiných háků.

Háky aplikací

Hooky aplikací se spouští jednou za instanci vaší aplikace, a to buď během spuštění v háku appStart , nebo během ukončení v háku appTerminate . Hooky pro ukončení aplikace mají omezený čas na spuštění a nespustí se u všech scénářů.

Modul runtime Azure Functions aktuálně nepodporuje protokolování kontextu mimo vyvolání. Pomocí balíčku npm Application Insights můžete logovat data během aplikačních hooků.

Následující příklad zaregistruje háky aplikací:

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

app.hook.appStart((context) => {
    // add your logic here
});

app.hook.appTerminate((context) => {
    // add your logic here
});

Prvním argumentem obslužné rutiny háku je kontextový objekt specifický pro daný typ háku.

Objekt AppStartContext má následující vlastnosti:

Vlastnost Popis
hookData Doporučené místo pro ukládání a sdílení dat mezi hooky ve stejném rozsahu. Měli byste použít jedinečný název vlastnosti, aby nebyl v konfliktu s daty jiných háků.

Objekt AppTerminateContext má následující vlastnosti:

Vlastnost Popis
hookData Doporučené místo pro ukládání a sdílení dat mezi hooky ve stejném rozsahu. Měli byste použít jedinečný název vlastnosti, aby nebyl v konfliktu s daty jiných háků.

Škálování a souběžnost

Ve výchozím nastavení Azure Functions automaticky monitoruje zatížení vaší aplikace a podle potřeby vytvoří více instancí hostitele pro Node.js. Azure Functions používá integrované (ne konfigurovatelné) prahové hodnoty pro různé typy aktivačních událostí, aby se rozhodli, kdy přidat instance, jako je věk zpráv a velikost fronty pro QueueTrigger. Další informace najdete v tématu Jak fungují plány Consumption a Premium.

Toto chování škálování je dostatečné pro mnoho Node.js aplikací. U aplikací vázaných na procesor můžete výkon dále zlepšit pomocí více jazykových pracovních procesů. Pomocí nastavení aplikace FUNCTIONS_WORKER_PROCESS_COUNT můžete zvýšit počet pracovních procesů na hostitele z výchozí hodnoty 1 až na 10. Azure Functions se pak pokusí rovnoměrně distribuovat souběžné vyvolání funkcí napříč těmito pracovními procesy. Díky tomuto chování je méně pravděpodobné, že funkce náročná na procesor blokuje spuštění dalších funkcí. Toto nastavení platí pro každého hostitele, kterého Azure Functions vytvoří při škálování aplikace pro splnění poptávky.

Varování

FUNCTIONS_WORKER_PROCESS_COUNT Nastavení používejte s opatrností. Několik procesů spuštěných ve stejné instanci může způsobit nepředvídatelné chování a zvýšit dobu načítání funkcí. Pokud použijete toto nastavení, důrazně doporučujeme , abyste tyto nevýhody odsadily spuštěním ze souboru balíčku.

Verze Node.js

Aktuální verzi, kterou modul runtime používá, můžete zobrazit pomocí protokolování process.version z libovolné funkce. Seznam supported versions verzí Node.js podporovaných každým programovacím modelem

Nastavení verze uzlu

Způsob upgradu Node.js verze závisí na operačním systému, na kterém běží vaše aplikace funkcí.

Při spuštění na Windows se Node.js verze nastaví nastavením aplikace WEBSITE_NODE_DEFAULT_VERSION. Toto nastavení je možné aktualizovat pomocí Azure CLI nebo na portálu Azure.

Další informace o verzích Node.js naleznete v tématu Podporované verze.

Před upgradem Node.js verze se ujistěte, že je vaše aplikace funkcí spuštěná na nejnovější verzi modulu runtime Azure Functions. Pokud potřebujete upgradovat verzi modulu runtime, přečtěte si téma Migrace aplikací z Azure Functions verze 3.x na verzi 4.x.

Spuštěním příkazu Azure CLI az functionapp config appsettings set aktualizujte verzi Node.js aplikace funkcí spuštěnou na Windows:

az functionapp config appsettings set  --settings WEBSITE_NODE_DEFAULT_VERSION=~22 \
 --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME>

Tím se nastaví WEBSITE_NODE_DEFAULT_VERSION nastavení aplikace na podporovanou verzi LTS ~22.

Po provedení změn se vaše aplikace funkce restartuje. Další informace o podpoře služby Functions pro Node.js najdete v dokumentu Politika podpory runtime jazyka.

Proměnné prostředí

Proměnné prostředí mohou být užitečné pro provozní tajné informace (připojovací řetězce, klíče, koncové body atd.) nebo nastavení prostředí, jako jsou profilovací proměnné. Proměnné prostředí můžete přidat v místním i cloudovém prostředí a přistupovat k nim prostřednictvím process.env kódu funkce.

Následující příklad zaznamená proměnnou WEBSITE_SITE_NAME prostředí:

module.exports = async function (context) {
  context.log(`WEBSITE_SITE_NAME: ${process.env["WEBSITE_SITE_NAME"]}`);
};

async function timerTrigger1(myTimer, context) {
  context.log(`WEBSITE_SITE_NAME: ${process.env["WEBSITE_SITE_NAME"]}`);
}

V místním vývojovém prostředí

Při místním spuštění projekt funkcí obsahuje local.settings.json soubor, do kterého ukládáte proměnné prostředí v objektu Values .

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "CUSTOM_ENV_VAR_1": "hello",
    "CUSTOM_ENV_VAR_2": "world"
  }
}

V cloudovém prostředí Azure

Když spustíte Azure, aplikace funkcí umožňuje nastavit a používat nastavení Aplication, jako jsou připojovací řetězce služby, a během provádění tato nastavení zpřístupní jako proměnné prostředí.

Nastavení aplikace funkcí můžete přidat, aktualizovat a odstranit několika způsoby:

Změny nastavení aplikace funkcí vyžadují restartování aplikace funkcí.

Proměnné pracovního prostředí

Existuje několik proměnných prostředí functions specifických pro Node.js:

LanguageWorkersuzluargumenty

Toto nastavení umožňuje zadat vlastní argumenty při spuštění procesu Node.js. Nejčastěji se používá místně ke spuštění pracovního procesu v režimu ladění, ale můžete ho použít také v Azure, pokud potřebujete vlastní argumenty.

Varování

Pokud je to možné, vyhněte se použití languageWorkers__node__arguments v Azure, protože může mít negativní vliv na časy studených startů. Místo použití předem připravených pracovních procesů musí modul runtime spustit nový pracovní proces úplně od začátku s vašimi vlastními argumenty.

logovánílogLevelPracovník

Toto nastavení upraví výchozí úroveň protokolu pro protokoly pracovních procesů specifických pro Node.js. Ve výchozím nastavení se zobrazují pouze protokoly upozornění nebo chyb, ale můžete to nastavit na information nebo debug pro pomoc s diagnostikou problémů s pracovní procesem Node.js. Další informace najdete v tématu konfigurace úrovní protokolu.

Moduly ECMAScript (Náhled)

Poznámka:

Vzhledem k tomu, že moduly ECMAScript jsou v současné době ve verzi Preview ve verzi Node.js 14 nebo vyšší v Azure Functions.

Moduly ECMAScript (moduly ES) jsou novým oficiálním standardním systémem modulů pro Node.js. Zatím ukázky kódu v tomto článku používají syntaxi CommonJS. Při spouštění Azure Functions ve Node.js 14 nebo novějších můžete psát funkce pomocí syntaxe modulů ES.

Pokud chcete ve funkci používat moduly ES, změňte jeho název souboru tak, aby používal příponu .mjs . Následující příklad souboru index.mjs je funkce aktivovaná protokolem HTTP, která k importu uuid knihovny používá syntaxi modulů ES a vrací hodnotu.

import { v4 as uuidv4 } from "uuid";

async function httpTrigger1(context, request) {
  context.res.body = uuidv4();
}

export default httpTrigger;

import { v4 as uuidv4 } from "uuid";

async function httpTrigger1(request, context) {
  return { body: uuidv4() };
}

app.http("httpTrigger1", {
  methods: ["GET", "POST"],
  handler: httpTrigger1,
});

Konfigurace vstupního bodu funkce

Vlastnosti function.jsonscriptFile a entryPoint lze je použít ke konfiguraci umístění a názvu exportované funkce. Vlastnost scriptFile je vyžadována při použití TypeScriptu a měla by odkazovat na zkompilovaný JavaScript.

Použití scriptFile

Ve výchozím nastavení je javascriptová funkce spuštěna ze index.jssouboru, který sdílí stejný nadřazený adresář jako odpovídající function.json.

scriptFile lze použít k získání struktury složek, která vypadá jako v následujícím příkladu:

<project_root>/
 | - node_modules/
 | - myFirstFunction/
 | | - function.json
 | - lib/
 | | - sayHello.js
 | - host.json
 | - package.json

Hodnota function.json pro myFirstFunction by měla obsahovat atribut scriptFile, který odkazuje na soubor s exportovanou funkcí, jež se má spustit.

{
  "scriptFile": "../lib/sayHello.js",
  "bindings": [
    ...
  ]
}

Použití entryPoint

V modelu v3 musí být funkce exportována pomocí module.exports , aby byla nalezena a spuštěna. Ve výchozím nastavení je funkce, která se spustí při aktivaci, jediným exportem z daného souboru, exportem s názvem runnebo exportem s názvem index. Následující příklad nastaví entryPoint v function.json na vlastní hodnotu „logHello“:

{
  "entryPoint": "logHello",
  "bindings": [
    ...
  ]
}

async function logHello(context) {
  context.log("Hello, world!");
}

module.exports = { logHello };

Místní ladění

Doporučujeme použít VS Code pro místní ladění, které spustí proces Node.js v režimu ladění automaticky a připojí se k procesu za vás. Další informace najdete v tématu místní spuštění funkce.

Pokud k ladění používáte jiný nástroj nebo chcete spustit proces Node.js v režimu ladění ručně, přidejte "languageWorkers__node__arguments": "--inspect"Values do local.settings.json. Argument --inspect říká, aby Node.js naslouchal ladicímu klientovi na portu 9229 ve výchozím nastavení. Další informace najdete v průvodci laděním Node.js.

Doporučení

Tato část popisuje několik působivých vzorů pro Node.js aplikace, které doporučujeme sledovat.

Volba plánů služby App Service s jedním virtuálním procesorem

Při vytváření aplikace funkcí, která používá plán služby App Service, doporučujeme místo plánu s více virtuálními procesory vybrat plán vCPU s jedním virtuálním procesorem. V současné době functions běží Node.js funkce efektivněji na virtuálních počítačích s jedním virtuálním procesorem a použití větších virtuálních počítačů nevygeneruje očekávané vylepšení výkonu. V případě potřeby můžete ručně škálovat přidáním dalších instancí virtuálních počítačů s jedním virtuálním procesorem nebo povolením automatického škálování. Další informace najdete v tématu Ruční nebo automatické škálování počtu instancí.

Spuštění ze souboru balíčku

Při vývoji Azure Functions v modelu bezserverového hostování jsou studené starty realitou. Studený start označuje první spuštění aplikace využívající funkce po určité době nečinnosti, což způsobí, že spuštění trvá déle. U Node.js aplikací s velkými stromy závislostí může být důležité zejména studené spuštění. Pokud chcete urychlit proces studeného spuštění, spusťte funkce jako soubor balíčku, pokud je to možné. Mnoho metod nasazení používá tento model ve výchozím nastavení, ale pokud máte velké studené starty, měli byste zkontrolovat, že tímto způsobem pracujete.

Použití jednoho statického klienta

Při použití klienta specifického pro službu v aplikaci Azure Functions nevytvořte nového klienta s každým vyvoláním funkce, protože můžete využít limity připojení. Místo toho vytvořte jednoho statického klienta v globálním oboru. Další informace najdete v tématu spravování připojení v Azure Functions.

Použijte async a await

Při psaní Azure Functions v Node.jsbyste měli psát kód pomocí klíčových slov async a await. Psaní kódu pomocí async a await místo zpětného volání nebo .then a .catch s přísliby pomáhá vyhnout se dvěma běžným problémům:

  • Vyvolání nezachycených výjimek, které způsobí pád procesu Node.js, což může negativně ovlivnit provádění jiných funkcí.
  • Neočekávané chování, například chybějící protokoly context.log, způsobené asynchronními voláními, která nejsou správně očekávána.

V následujícím příkladu je asynchronní metoda fs.readFile vyvolána s funkcí zpětného volání typu error-first jako svým druhým parametrem. Tento kód způsobuje oba dříve uvedené problémy. Výjimka, která není explicitně zachycena ve správném oboru, může způsobit havárii celého procesu (problém č. 1). Vrácení bez zajištění dokončení zpětného volání znamená, že odpověď HTTP má někdy prázdný text (problém č. 2).

// DO NOT USE THIS CODE
const { app } = require('@azure/functions');
const fs = require('fs');

app.http('httpTriggerBadAsync', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        let fileData;
        fs.readFile('./helloWorld.txt', (err, data) => {
            if (err) {
                context.error(err);
                // BUG #1: This will result in an uncaught exception that crashes the entire process
                throw err;
            }
            fileData = data;
        });
        // BUG #2: fileData is not guaranteed to be set before the invocation ends
        return { body: fileData };
    },
});

V následujícím příkladu je asynchronní metoda fs.readFile vyvolána s funkcí zpětného volání typu error-first jako svým druhým parametrem. Tento kód způsobuje oba dříve uvedené problémy. Výjimka, která není explicitně zachycena ve správném oboru, může způsobit havárii celého procesu (problém č. 1). Volání zastaralé context.done() metody mimo rozsah zpětného volání může signalizovat, že funkce je dokončena před čtením souboru (problém č. 2). V tomto příkladu volání context.done() příliš brzy způsobí chybějící položky protokolu začínající na Data from file:.

// NOT RECOMMENDED PATTERN
const fs = require("fs");

module.exports = function (context) {
  fs.readFile("./hello.txt", (err, data) => {
    if (err) {
      context.log.error("ERROR", err);
      // BUG #1: This will result in an uncaught exception that crashes the entire process
      throw err;
    }
    context.log(`Data from file: ${data}`);
    // context.done() should be called here
  });
  // BUG #2: Data is not guaranteed to be read before the Azure Function's invocation ends
  context.done();
};

Pomocí klíčových slov async a await se můžete vyhnout oběma těmto problémům. Většina rozhraní API v ekosystému Node.js byla v nějaké podobě převedena na přísliby podpory. Například od verze v14 poskytuje Node.js rozhraní fs/promises API pro nahrazení API s fs zpětným voláním.

V následujícím příkladu jakékoli neošetřené výjimky vyvolané během provádění funkce způsobí selhání pouze jednotlivého vyvolání, které vyvolalo výjimku. Klíčové await slovo znamená, že následující readFile kroky se spustí až po jeho dokončení.

// Recommended pattern
const { app } = require('@azure/functions');
const fs = require('fs/promises');

app.http('httpTriggerGoodAsync', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        try {
            const fileData = await fs.readFile('./helloWorld.txt');
            return { body: fileData };
        } catch (err) {
            context.error(err);
            // This rethrown exception will only fail the individual invocation, instead of crashing the whole process
            throw err;
        }
    },
});

S async a await také nemusíte volat context.done() callback.

// Recommended pattern
const fs = require("fs/promises");

module.exports = async function (context) {
  let data;
  try {
    data = await fs.readFile("./hello.txt");
  } catch (err) {
    context.log.error("ERROR", err);
    // This rethrown exception will be handled by the Functions Runtime and will only fail the individual invocation
    throw err;
  }
  context.log(`Data from file: ${data}`);
};

Odstraňování potíží

Přečtěte si průvodce odstraňováním potíží s Node.js.

Další kroky

Další informace naleznete v následujících zdrojích:

  • Last updated on