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

Bu makale, Node.js programlama modelinin 3. ve 4. sürümleri arasındaki farkları ve mevcut bir v3 uygulamasını nasıl yükselteceğimizi tartışmaktadı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ştiricilere aşağıdaki avantajları sağlayacak şekilde tasarlanmıştır:

• Node.js geliştiricilerine tanıdık ve sezgisel bir deneyim sunun.
• 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. Sürümleri, runtime'dan bağımsızdır. 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ızda bir v4 işlevi kaydettiğiniz anda, function.json dosyalarına kayıtlı tüm v3 işlevleri yok sayılır.

Gereksinimler

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

• @azure/functions npm paket v4.0.0
• Node.js v18+
• Azure İşlevleri Çalışma Zamanı v4.25+
• Azure İşlevleri Core Tools v4.0.5382+ (yerel olarak çalıştırılıyorsa)

• @azure/functions npm paket v4.0.0
• Node.js v18+
• TypeScript v4+
• Azure İşlevleri Çalışma Zamanı v4.25+
• Azure İşlevleri Core Tools v4.0.5382+ (yerel olarak çalıştırılıyorsa)

npm paketini dahil et

v4'te npm paketi, @azure/functions Node.js 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

@azure/functions paketinin dependencies dosyanızın devDependencies bölümünde ( değil) listelendiğinden 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.

Aksi takdirde, package.json dosyanızdaki main alanı ayarlayarak 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 fonksiyonu kendi dosyasından kaydedin.
src/{index.js,functions/*.js}	Her bir fonksiyonu kendi dosyasından kaydettiğiniz, ancak uygulama genelindeki kodlar için yine de bir kök dosya kullandığınız bir yaklaşım.

Örnek	Açıklama
dist/src/index.js	İşlevleri tek bir kök dosyadan kaydedin.
dist/src/functions/*.js	Her fonksiyonu kendi dosyasından kaydedin.
dist/src/{index.js,functions/*.js}	Her bir fonksiyonu kendi dosyasından kaydettiğiniz, ancak uygulama genelindeki kodlar için yine de bir kök dosya kullandığınız bir yaklaşım.

İpucu

main dosyanızda bir 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ğrı bağlamı, v4'te basitleştirilmiştir ve tetikleyici girişi kadar gerekli değildir. Kullanmıyorsanız kapalı bırakabilirsiniz.

İpucu

Argümanlarınızın sırasını değiştirin. Örneğin, bir HTTP tetikleyicisi kullanıyorsanız, (context, request) öğesini (request, context) ile veya bağlamı kullanmıyorsanız yalnızca (request) ile değiştirin.

İş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

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

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 girdi ve çıktıyı, yalnızca işlev işleyicinizin bağımsız değişkeni ve dönüş değeri üzerinden erişilecek şekilde sadeleştirdik.

context nesnesindeki birincil giriş ve çıkışlara artık erişemezsiniz, ancak yine de nesnesindeki context giriş ve çıkışlara erişmeniz gerekir. İkincil girişler ve çıkışlar hakkında daha fazla bilgi için Node.js geliştirici kılavuzuna bakın.

Birincil girdiyi argüman olarak al

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, tetikleyici girişini ilk bağımsız değişken olarak almanın yalnızca tek 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

Girdiyi almak için context.req veya context.bindings kullanmadığınızdan 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ı context nesnesiyle ayarlamak yerine, her zaman fonksiyon işleyicisinde döndürdüğünüzden emin olun.

Bağlam günlüğü

v4'te, aşağıdaki örnekte gösterildiği gibi günlükleme yöntemleri kök context nesnesine taşındı. Günlük kaydı hakkında daha fazla bilgi için Node.js geliştirici kılavuzuna bakın.

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, bunları kendiniz eklemediğiniz sürece testler sırasındaki bilgiler ayrıntılı olmasa da çağrı 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’de undici paketini kullanır. Bu paket, getirme standardına uyar ve şu anda Node.js çekirdekle tümleştiriliyor .

HttpRequest

v4

• Gövde. İçeriğe, almak istediğiniz türe özgü bir yöntem kullanarak erişebilirsiniz:

  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 birkaç farklı şekilde erişebilirsiniz, ancak döndürülen tip 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();
  

• Başlık. Üst bilgiyi çeşitli şekillerde elde edebilirsiniz:

  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 stringgibi Buffer ç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" } };
  

• Başlık. HttpResponse sınıfını mı yoksa HttpResponseInit arabirimini mi kullandığınıza 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!" };
  

• Başlık. Ü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ı anlamanıza yardımcı olmak için TypeScript derleme hatalarıyla karşılaşmalısınız.

Sorun giderme

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