Azure İşlevleri için Node.js programlama modelinin 4. sürümüne geçiş

Bu makalede Node.js programlama modelinin sürüm 3 ile sürüm 4 arasındaki farklar ve mevcut bir v3 uygulamasının nasıl yükseltılacağı açıklanır. Mevcut bir v3 uygulamasını yükseltmek yerine yeni bir v4 uygulaması oluşturmak istiyorsanız Visual Studio Code (VS Code) veya Azure İşlevleri Core Tools öğreticisine bakın. Bu makalede, uygulamanızı yükseltmek için gerçekleştirmeniz gereken en önemli somut eylemleri vurgulamak için "ipucu" uyarıları kullanılır.

Sürüm 4, Node.js geliştiricilerine aşağıdaki avantajları sağlayacak şekilde tasarlanmıştır:

• Node.js geliştiricilerine tanıdık ve sezgisel bir deneyim sağlayın.
• Tam özelleştirme desteğiyle dosya yapısını esnek hale getirin.
• İşlev yapılandırmasını tanımlamak için kod odaklı bir yaklaşıma geçin.

Dikkat edilmesi gereken noktalar

• Node.js programlama modeli Azure İşlevleri çalışma zamanıyla karıştırılmamalıdır:
  • Programlama modeli: Kodunuzu nasıl yazdığınızı tanımlar ve JavaScript ve TypeScript'e özgüdür.
  • Çalışma zamanı: Azure İşlevleri temel davranışını tanımlar ve tüm dillerde paylaşılır.
• Programlama modelinin sürümü kesinlikle npm paketinin sürümüne @azure/functions bağlıdır. Çalışma zamanından bağımsız olarak sürümlenmiştir. Hem çalışma zamanı hem de programlama modeli en son ana sürümü olarak 4 sayısını kullanır, ancak bu bir tesadüftür.
• Aynı işlev uygulamasında v3 ve v4 programlama modellerini karıştıramazsınız. Uygulamanıza bir v4 işlevi kaydettiğiniz anda function.json dosyalarına kayıtlı tüm v3 işlevleri yoksayılır.

Gereksinimler

Node.js programlama modelinin 4. sürümü aşağıdaki en düşük sürümleri gerektirir:

• @azure/functions npm paketi v4.0.0
• Node.js v18+
• Azure İşlevleri Runtime v4.25+
• Azure İşlevleri Core Tools v4.0.5382+ (yerel olarak çalışıyorsa)

• @azure/functions npm paketi v4.0.0
• Node.js v18+
• TypeScript v4+
• Azure İşlevleri Runtime v4.25+
• Azure İşlevleri Core Tools v4.0.5382+ (yerel olarak çalışıyorsa)

npm paketini dahil et

v4'te npm paketi Node.js @azure/functions programlama modelini destekleyen birincil kaynak kodunu içerir. Önceki sürümlerde bu kod doğrudan Azure'da gönderildi ve npm paketinde yalnızca TypeScript türleri vardı. Şimdi bu paketi hem TypeScript hem de JavaScript uygulamaları için eklemeniz gerekir. Mevcut v3 uygulamaları için paketi ekleyebilirsiniz, ancak bu gerekli değildir.

İpucu

Paketin @azure/functions package.json dosyanızın bölümünde (değildevDependencies) listelendiğinden dependencies emin olun. Aşağıdaki komutu kullanarak v4'ü yükleyebilirsiniz:

npm install @azure/functions

Uygulama giriş noktanızı ayarlama

Programlama modelinin v4'lerinde kodunuzu istediğiniz gibi yapılandırabilirsiniz. Uygulamanızın kökünde ihtiyacınız olan tek dosyalar host.json ve package.json dosyalarıdır.

Aksi takdirde, package.json dosyanızdaki alanı ayarlayarak main dosya yapısını tanımlarsınız. Glob deseni mainkullanarak alanı tek bir dosyaya veya birden çok dosyaya ayarlayabilirsiniz. Aşağıdaki tabloda alan için örnek değerler gösterilmektedir main :

Örnek	Açıklama
src/index.js	İşlevleri tek bir kök dosyadan kaydedin.
src/functions/*.js	Her işlevi kendi dosyasından kaydedin.
src/{index.js,functions/*.js}	Her işlevi kendi dosyasından kaydettiğiniz, ancak yine de genel uygulama düzeyinde kod için bir kök dosyanız olduğu bir birleşim.

Örnek	Açıklama
dist/src/index.js	İşlevleri tek bir kök dosyadan kaydedin.
dist/src/functions/*.js	Her işlevi kendi dosyasından kaydedin.
dist/src/{index.js,functions/*.js}	Her işlevi kendi dosyasından kaydettiğiniz, ancak yine de genel uygulama düzeyinde kod için bir kök dosyanız olduğu bir birleşim.

İpucu

package.json dosyanızda bir main alan tanımladığınızdan emin olun.

Bağımsız değişkenlerin sırasını değiştirme

Çağırma bağlamı yerine tetikleyici girişi artık işlev işleyicinizin ilk bağımsız değişkenidir. Artık ikinci bağımsız değişken olan çağırma bağlamı v4'te basitleştirilmiştir ve tetikleyici girişi olarak gerekli değildir. Kullanmıyorsanız kapalı bırakabilirsiniz.

İpucu

Bağımsız değişkenlerinizin sırasını değiştirin. Örneğin, HTTP tetikleyicisi kullanıyorsanız veya bağlamı (request) kullanmıyorsanız öğesine geçin.(request, context)(context, request)

İşlevinizi kodda tanımlama

Artık bu ayrı function.json yapılandırma dosyalarını oluşturmanız ve korumanız gerekmez. Artık işlevlerinizi doğrudan TypeScript veya JavaScript dosyalarınızda tam olarak tanımlayabilirsiniz. Buna ek olarak, artık birçok özelliğin varsayılan değerleri vardır, böylece bunları her seferinde belirtmeniz gerekmez.

v4

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

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        context.log(`Http function processed request for url "${request.url}"`);

        const name = request.query.get('name') || (await request.text()) || 'world';

        return { body: `Hello, ${name}!` };
    },
});

v3

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

    const name = req.query.name || req.body || 'world';

    context.res = {
        body: `Hello, ${name}!`
    };
};

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

v4

import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = request.query.get('name') || (await request.text()) || 'world';

    return { body: `Hello, ${name}!` };
}

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

v3

import { AzureFunction, Context, HttpRequest } from "@azure/functions"

const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = req.query.name || req.body || 'world';

    context.res = {
        body: `Hello, ${name}!`
    };
};

export default httpTrigger;

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ],
  "scriptFile": "../dist/HttpTrigger1/index.js"
}

İpucu

function.json dosyanızdaki yapılandırmayı kodunuzla taşıyın. Tetikleyicinin türü, yeni modeldeki nesnedeki app bir yönteme karşılık gelir. Örneğin, function.json içinde bir httpTrigger tür kullanıyorsanız, işlevi kaydetmek için kodunuzu çağırınapp.http(). kullanıyorsanız timerTriggerçağrısında bulunur app.timer().

Bağlam kullanımınızı gözden geçirin

v4'te nesne, context yinelemeyi azaltmak ve birim testleri yazmayı kolaylaştırmak için basitleştirilmiştir. Örneğin, birincil girişi ve çıkışı yalnızca işlev işleyicinizin bağımsız değişkeni ve dönüş değeri olarak erişilebilecek şekilde kolaylaştırdık.

Nesnedeki context birincil giriş ve çıkışa artık erişemezsiniz, ancak nesnedeki context ikincil girişlere ve çıkışlara erişmeye devam etmeniz gerekir. İkincil girişler ve çıkışlar hakkında daha fazla bilgi için bkz . Node.js geliştirici kılavuzu.

Birincil girişi bağımsız değişken olarak alma

Birincil giriş tetikleyici olarak da adlandırılır ve tek gerekli giriş veya çıkıştır. Bir (ve yalnızca bir) tetikleyiciniz olmalıdır.

v4

Sürüm 4, ilk bağımsız değişken olarak tetikleyici girişini almanın yalnızca bir yolunu destekler:

async function httpTrigger1(request, context) {
  const onlyOption = request;

async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
  const onlyOption = request;

v3

Sürüm 3, tetikleyici girişini almanın çeşitli yollarını destekler:

async function httpTrigger1(context, request) {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

async function httpTrigger1(context: Context, req: HttpRequest): Promise<void> {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

İpucu

Girişi almak için veya context.bindings kullanmadığınızdan context.req emin olun.

Birincil çıkışı dönüş değeriniz olarak ayarlayın

v4

Sürüm 4, birincil çıkışı dönüş değeri aracılığıyla ayarlamanın tek bir yolunu destekler:

return { 
  body: `Hello, ${name}!` 
};

async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    // ...
    return { 
      body: `Hello, ${name}!` 
    };
}

v3

Sürüm 3, birincil çıkışı ayarlamanın çeşitli yollarını destekler:

// Option 1
context.res = {
    body: `Hello, ${name}!`
};
// Option 2, but you can't use this option with any async code:
context.done(null, {
    body: `Hello, ${name}!`
});
// Option 3, but you can't use this option with any async code:
context.res.send(`Hello, ${name}!`);
// Option 4, if "name" in function.json is "res":
context.bindings.res = {
    body: `Hello, ${name}!`
}
// Option 5, if "name" in function.json is "$return":
return {
    body: `Hello, ${name}!`
};

İpucu

Çıktıyı nesneyle ayarlamak yerine her zaman işlev işleyicinizde döndürdiğinizden context emin olun.

Bağlam günlüğü

v4'te, aşağıdaki örnekte gösterildiği gibi günlük yöntemleri kök context nesneye taşındı. Günlüğe kaydetme hakkında daha fazla bilgi için bkz . Node.js geliştirici kılavuzu.

v4

context.log('This is an info log');
context.error('This is an error');
context.warn('This is an error');

v3

context.log('This is an info log');
context.log.error('This is an error');
context.log.warn('This is an error');

Test bağlamı oluşturma

Sürüm 3, Azure İşlevleri çalışma zamanı dışında bir çağrı bağlamı oluşturmayı desteklemez, bu nedenle birim testleri yazmak zor olabilir. Sürüm 4, siz eklemediğiniz sürece testler sırasındaki bilgiler ayrıntılı olmasa da çağırma bağlamının bir örneğini oluşturmanıza olanak tanır.

v4

const testInvocationContext = new InvocationContext({
  functionName: 'testFunctionName',
  invocationId: 'testInvocationId'
});

v3

Mümkün değil.

HTTP türleri kullanımınızı gözden geçirin

HTTP isteği ve yanıt türleri artık getirme standardının bir alt kümesidir. Bunlar artık Azure İşlevleri için benzersiz değildir.

Türler Node.js dosyasında paketini kullanır undici . Bu paket getirme standardına uyar ve şu anda Node.js core ile tümleştiriliyor .

HttpRequest

v4

• Gövde. Gövdeye erişmek için almak istediğiniz türe özgü bir yöntem kullanabilirsiniz:

  const body = await request.text();
  const body = await request.json();
  const body = await request.formData();
  const body = await request.arrayBuffer();
  const body = await request.blob();
  

• Üst Bilgi:

  const header = request.headers.get('content-type');
  

• Sorgu parametresi:

  const name = request.query.get('name');
  

v3

• Gövde. Gövdeye çeşitli yollarla erişebilirsiniz, ancak döndürülen tür her zaman tutarlı değildir:

  // returns a string, object, or Buffer
  const body = request.body;
  // returns a string
  const body = request.rawBody;
  // returns a Buffer
  const body = request.bufferBody;
  // returns an object representing a form
  const body = await request.parseFormBody();
  

• Üst bilgi. Üst bilgiyi çeşitli yollarla alabilirsiniz:

  const header = request.get('content-type');
  const header = request.headers.get('content-type');
  const header = context.bindingData.headers['content-type'];
  

• Sorgu parametresi:

  const name = request.query.name;
  

HttpResponse

v4

• Durum:

  return { status: 200 };
  

• Gövde:

  body veya Buffergibi string çoğu türü döndürmek için özelliğini kullanın:

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

  jsonBody JSON yanıtı döndürmenin en kolay yolu için özelliğini kullanın:

  return { jsonBody: { hello: "world" } };
  

• Üst bilgi. Sınıfı mı HttpResponseInit yoksa arabirimi mi kullandığınıza HttpResponse bağlı olarak üst bilgiyi iki şekilde ayarlayabilirsiniz:

  const response = new HttpResponse();
  response.headers.set('content-type', 'application/json');
  return response;
  

  return {
    headers: { 'content-type': 'application/json' }
  };
  

v3

• Durum. Durumu çeşitli yollarla ayarlayabilirsiniz:

  context.res.status(200);
  context.res = { status: 200}
  context.res = { statusCode: 200 };
  return { status: 200};
  return { statusCode: 200 };
  

• Gövde. Gövdeyi çeşitli yollarla ayarlayabilirsiniz ve gövde türüne (string, , BufferJSON nesnesi vb.) bakılmaksızın aynı olur:

  context.res.send("Hello, world!");
  context.res.end("Hello, world!");
  context.res = { body: "Hello, world!" };
  return { body: "Hello, world!" };
  

• Üst bilgi. Üst bilgiyi çeşitli yollarla ayarlayabilirsiniz:

  response.set('content-type', 'application/json');
  response.setHeader('content-type', 'application/json');
  response.headers = { 'content-type': 'application/json' }
  context.res = {
    headers: { 'content-type': 'application/json' }
  };
  return {
    headers: { 'content-type': 'application/json' }
  };
  

İpucu

HTTP isteğini veya yanıt türlerini kullanarak tüm mantığı yeni yöntemlerle eşleşecek şekilde güncelleştirin.

İpucu

HTTP isteğini veya yanıt türlerini kullanarak tüm mantığı yeni yöntemlerle eşleşecek şekilde güncelleştirin. Eski yöntemleri kullanıp kullanmadığınızı belirlemenize yardımcı olması için TypeScript derleme hataları almanız gerekir.

Sorun giderme

Node.js Sorun Giderme kılavuzuna bakın.