Så här använder du Node.js SDK för Azure Mobile Apps

Den här artikeln innehåller detaljerad information och exempel som visar hur du arbetar med en NodeJS-serverdel för Azure Mobile Apps.

Introduktion

Azure Mobile Apps ger möjlighet att lägga till en mobiloptimerad dataåtkomstwebb-API till ett webbprogram. Azure Mobile Apps SDK tillhandahålls för ASP.NET Framework- och Node.js-webbprogram. SDK:et tillhandahåller följande åtgärder:

• Tabellåtgärder (läsa, infoga, uppdatera, ta bort) för dataåtkomst
• Anpassade API-åtgärder

Båda åtgärderna tillhandahåller autentisering för alla identitetsprovidrar som Azure App Service tillåter. Dessa leverantörer omfattar sociala identitetsprovidrar som Facebook, Twitter, Google och Microsoft och Microsoft Entra ID för företagsidentitet.

Plattformar som stöds

Azure Mobile Apps Node.js SDK stöder Node 6.x och senare och har testats upp till Nod 12.x. Andra versioner av Node kan fungera men stöds inte.

Azure Mobile Apps Node.js SDK stöder två databasdrivrutiner:

• Node-mssql-drivrutinen stöder Azure SQL Database och lokala SQL Server-instanser.
• Sqlite3-drivrutinen stöder endast SQLite-databaser på en enda instans.

Skapa en grundläggande nodserverdel med hjälp av kommandoraden

Varje Azure Mobile Apps Node.js-serverdel startar som ett Express-program . Express är det populäraste webbtjänstramverket som är tillgängligt för Node.js. Du kan skapa ett grundläggande Express-program på följande sätt:

1. I ett kommando eller PowerShell-fönster skapar du en katalog för projektet:

   $ mkdir basicapp
   

2. Kör npm init för att initiera paketstrukturen:

   $ cd basicapp
   $ npm init
   

   Kommandot npm init ställer en uppsättning frågor för att initiera projektet. Se exempelutdata:

   

3. Installera biblioteken express och azure-mobile-apps från npm-lagringsplatsen:

   npm install --save express azure-mobile-apps
   

4. Skapa en app.js fil för att implementera den grundläggande mobila servern:

   var express = require('express'),
       azureMobileApps = require('azure-mobile-apps');
   
   var app = express(),
       mobile = azureMobileApps();
   
   // Define a TodoItem table.
   mobile.tables.add('TodoItem');
   
   // Add the Mobile API so it is accessible as a Web API.
   app.use(mobile);
   
   // Start listening on HTTP.
   app.listen(process.env.PORT || 3000);
   

Det här programmet skapar ett mobiloptimerad webb-API med en enda slutpunkt (/tables/TodoItem) som ger oautentiserad åtkomst till ett underliggande SQL-datalager med hjälp av ett dynamiskt schema. Den är lämplig för att följa snabbstarterna för klientbiblioteket:

• Apache Cordova
• Windows (UWP)
• Windows (WPF)
• Xamarin.Android
• Xamarin.Forms
• Xamarin.iOS

Du hittar koden för det här grundläggande programmet i exempelområdet på GitHub.

Aktivera en startsida för ditt program

Många program är en kombination av webb- och mobilappar. Du kan använda Express-ramverket för att kombinera de två fasetter. Ibland kanske du dock bara vill implementera ett mobilt gränssnitt. Det är användbart att tillhandahålla en startsida för att säkerställa att apptjänsten är igång. Du kan antingen ange en egen startsida eller aktivera en tillfällig startsida. Om du vill aktivera en tillfällig startsida använder du följande kod för att instansiera Azure Mobile Apps:

var mobile = azureMobileApps({ homePage: true });

Om du bara vill att det här alternativet ska vara tillgängligt när du utvecklar lokalt kan du lägga till den här inställningen i konfigurationsfilen azureMobile.js :

module.exports = {
    homePage: true,
};

Du kan lägga till andra inställningar i filen azureMobile.js efter behov.

Tabellåtgärder

Azure-mobile-apps Node.js Server SDK tillhandahåller mekanismer för att exponera datatabeller som lagras i Azure SQL Database som ett webb-API. Den innehåller fem åtgärder:

Det här webb-API:et stöder OData v3 och utökar tabellschemat för att stödja datasynkronisering offline.

Definiera tabeller med hjälp av ett dynamiskt schema

Innan du kan använda en tabell måste du definiera den. Du kan definiera tabeller med hjälp av ett statiskt schema (där du definierar kolumnerna i schemat) eller dynamiskt (där SDK:t styr schemat baserat på inkommande begäranden). Dessutom kan du styra specifika aspekter av webb-API:et genom att lägga till JavaScript-kod i definitionen.

Som bästa praxis bör du definiera varje tabell i en JavaScript-fil i tables katalogen och sedan använda tables.import() metoden för att importera tabellerna. Om du utökar basic-app-exemplet justerar du filen app.js:

var express = require('express'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Define the database schema that is exposed.
mobile.tables.import('./tables');

// Provide initialization of any tables that are statically defined.
mobile.tables.initialize().then(function () {
    // Add the Mobile API so it is accessible as a Web API.
    app.use(mobile);

    // Start listening on HTTP.
    app.listen(process.env.PORT || 3000);
});

Definiera tabellen i ./tables/TodoItem.js:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Additional configuration for the table goes here.

module.exports = table;

Tabeller använder ett dynamiskt schema som standard.

Definiera tabeller med hjälp av ett statiskt schema

Du kan uttryckligen definiera vilka kolumner som ska exponeras via webb-API:et. Azure-mobile-apps Node.js SDK lägger automatiskt till eventuella extra kolumner som krävs för offline-datasynkronisering i listan som du anger. Till exempel kräver snabbstartsklientprogrammen en tabell med två kolumner: text (en sträng) och complete (ett booleskt värde). Tabellen kan definieras i tabelldefinitionens JavaScript-fil (finns i tables katalogen) på följande sätt:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

module.exports = table;

Om du definierar tabeller statiskt måste du även anropa tables.initialize() metoden för att skapa databasschemat vid start. Metoden tables.initialize() returnerar ett löfte så att webbtjänsten inte hanterar begäranden innan databasen initieras.

Använda SQL Server Express som ett datalager för utveckling på din lokala dator

Azure Mobile Apps Node.js SDK innehåller tre alternativ för att hantera data direkt:

• Använd minnesdrivrutinen för att tillhandahålla ett icke-beständigt exempelarkiv.
• Använd mssql-drivrutinen för att tillhandahålla ett SQL Server Express-datalager för utveckling.
• Använd mssql-drivrutinen för att tillhandahålla ett Azure SQL Database-datalager för produktion.

Azure Mobile Apps Node.js SDK använder mssql Node.js-paketet för att upprätta och använda en anslutning till både SQL Server Express och SQL Database. Det här paketet kräver att du aktiverar TCP-anslutningar på SQL Server Express-instansen.

1. Ladda ned och installera Microsoft SQL Server 2019 Developer.

2. Kör Configuration Manager:

   • Expandera noden SQL Server-nätverkskonfiguration i trädmenyn.
   • Välj Protokoll som instansnamn.
   • Högerklicka på TCP/IP och välj Aktivera. Välj OK i popup-dialogrutan.
   • Välj SQL Server Services i trädmenyn.
   • Högerklicka på SQL Server (instansnamn) och välj Starta om.
   • Stäng Configuration Manager.

Du måste också skapa ett användarnamn och lösenord som Azure Mobile Apps kan använda för att ansluta till databasen. Kontrollera att användaren du skapar har serverrollen dbcreator . Mer information om hur du konfigurerar användare finns i SQL Server-dokumentationen

Se till att registrera användarnamnet och lösenordet som du har valt. Du kan behöva tilldela fler serverroller eller behörigheter, beroende på dina databaskrav.

Node.js-programmet läser SQLCONNSTR_MS_TableConnectionString miljövariabeln för anslutningssträng för den här databasen. Du kan ange den här variabeln i din miljö. Du kan till exempel använda PowerShell för att ange den här miljövariabeln:

$env:SQLCONNSTR_MS_TableConnectionString = "Server=127.0.0.1; Database=mytestdatabase; User Id=azuremobile; Password=T3stPa55word;"

Få åtkomst till databasen via en TCP/IP-anslutning. Ange ett användarnamn och lösenord för anslutningen.

Konfigurera projektet för lokal utveckling

Azure Mobile Apps läser en JavaScript-fil som anropas azureMobile.js från det lokala filsystemet. Använd inte den här filen för att konfigurera Azure Mobile Apps SDK i produktion. Använd i stället Appinställningar i Azure-portalen.

Filen azureMobile.js bör exportera ett konfigurationsobjekt. De vanligaste inställningarna är:

• Databasinställningar
• Inställningar för diagnostikloggning
• Alternativa CORS-inställningar

I det här exemplet implementerar filen azureMobile.js de föregående databasinställningarna:

module.exports = {
    cors: {
        origins: [ 'localhost' ]
    },
    data: {
        provider: 'mssql',
        server: '127.0.0.1',
        database: 'mytestdatabase',
        user: 'azuremobile',
        password: 'T3stPa55word'
    },
    logging: {
        level: 'verbose'
    }
};

Vi rekommenderar att du lägger till azureMobile.js i .gitignore filen (eller annan källkodskontroll ignorerar fil) för att förhindra att lösenord lagras i molnet.

Konfigurera appinställningar för din mobilapp

De flesta inställningar i azureMobile.js filen har en motsvarande appinställning i Azure-portalen. Använd följande lista för att konfigurera din app i Appinställningar:

För att ändra de flesta appinställningar krävs en omstart av tjänsten.

Använda Azure SQL som produktionsdatalager

Att använda Azure SQL Database som ett datalager är identiskt för alla Azure App Service-programtyper. Om du inte redan har gjort det följer du de här stegen för att skapa en Azure App Service-serverdel. Skapa en Azure SQL-instans och ange sedan appinställningen SQLCONNSTR_MS_TableConnectionString till anslutningssträng för den Azure SQL-instans som du vill använda. Se till att Den Azure App Service som kör serverdelen kan kommunicera med din Azure SQL-instans.

Kräv autentisering för åtkomst till tabeller

Om du vill använda App Service-autentisering med tables slutpunkten måste du konfigurera App Service-autentisering i Azure-portalen först. Mer information finns i konfigurationsguiden för den identitetsprovider som du tänker använda:

• Konfigurera Microsoft Entra-autentisering
• Konfigurera Facebook-autentisering
• Konfigurera Google-autentisering
• Konfigurera Microsoft-autentisering
• Konfigurera Twitter-autentisering

Varje tabell har en åtkomstegenskap som du kan använda för att styra åtkomsten till tabellen. I följande exempel visas en statiskt definierad tabell med nödvändig autentisering.

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

Åtkomstegenskapen kan innehålla något av tre värden:

• anonym anger att klientprogrammet får läsa data utan autentisering.
• autentiserad anger att klientprogrammet måste skicka en giltig autentiseringstoken med begäran.
• inaktiverad anger att den här tabellen för närvarande är inaktiverad.

Om åtkomstegenskapen är odefinierad tillåts oautentiserad åtkomst.

Använda autentiseringsanspråk med dina tabeller

Du kan konfigurera olika anspråk som begärs när autentiseringen har konfigurerats. Dessa anspråk är normalt inte tillgängliga via objektet context.user . Du kan dock hämta dem med hjälp context.user.getIdentity() av metoden . Metoden getIdentity() returnerar ett löfte som matchar ett objekt. Objektet styrs av autentiseringsmetoden (facebook, , googletwitter, microsoftaccounteller aad).

Om du till exempel konfigurerar Microsoft Entra-autentisering och begär anspråket på e-postadresser kan du lägga till e-postadressen i posten med följande tabellkontrollant:

var azureMobileApps = require('azure-mobile-apps');

// Create a new table definition.
var table = azureMobileApps.table();

table.columns = {
    "emailAddress": "string",
    "text": "string",
    "complete": "boolean"
};
table.dynamicSchema = false;
table.access = 'authenticated';

/**
* Limit the context query to those records with the authenticated user email address
* @param {Context} context the operation context
* @returns {Promise} context execution Promise
*/
function queryContextForEmail(context) {
    return context.user.getIdentity().then((data) => {
        context.query.where({ emailAddress: data.aad.claims.emailaddress });
        return context.execute();
    });
}

/**
* Adds the email address from the claims to the context item - used for
* insert operations
* @param {Context} context the operation context
* @returns {Promise} context execution Promise
*/
function addEmailToContext(context) {
    return context.user.getIdentity().then((data) => {
        context.item.emailAddress = data.aad.claims.emailaddress;
        return context.execute();
    });
}

// Configure specific code when the client does a request.
// READ: only return records that belong to the authenticated user.
table.read(queryContextForEmail);

// CREATE: add or overwrite the userId based on the authenticated user.
table.insert(addEmailToContext);

// UPDATE: only allow updating of records that belong to the authenticated user.
table.update(queryContextForEmail);

// DELETE: only allow deletion of records that belong to the authenticated user.
table.delete(queryContextForEmail);

module.exports = table;

Om du vill se vilka anspråk som är tillgängliga använder du en webbläsare för att visa /.auth/me webbplatsens slutpunkt.

Inaktivera åtkomst till specifika tabellåtgärder

Förutom att visas i tabellen kan åtkomstegenskapen användas för att styra enskilda åtgärder. Det finns fyra åtgärder:

• read är RESTful GET-åtgärden i tabellen.
• insert är RESTful POST-åtgärden i tabellen.
• update är RESTful PATCH-åtgärden i tabellen.
• delete är RESTful DELETE-åtgärden i tabellen.

Du kanske till exempel vill ange en skrivskyddad oautentiserad tabell:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Read-only table. Only allow READ operations.
table.read.access = 'anonymous';
table.insert.access = 'disabled';
table.update.access = 'disabled';
table.delete.access = 'disabled';

module.exports = table;

Justera frågan som används med tabellåtgärder

Ett vanligt krav för tabellåtgärder är att tillhandahålla en begränsad vy av data. Du kan till exempel ange en tabell som är taggad med det autentiserade användar-ID:t så att du bara kan läsa eller uppdatera dina egna poster. Följande tabelldefinition innehåller följande funktioner:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define a static schema for the table.
table.columns = {
    "userId": "string",
    "text": "string",
    "complete": "boolean"
};
table.dynamicSchema = false;

// Require authentication for this table.
table.access = 'authenticated';

// Ensure that only records for the authenticated user are retrieved.
table.read(function (context) {
    context.query.where({ userId: context.user.id });
    return context.execute();
});

// When adding records, add or overwrite the userId with the authenticated user.
table.insert(function (context) {
    context.item.userId = context.user.id;
    return context.execute();
});

module.exports = table;

Åtgärder som normalt kör en fråga har en frågeegenskap som du kan justera med hjälp av en where sats. Frågeegenskapen är ett QueryJS-objekt som används för att konvertera en OData-fråga till något som dataserverdelen kan bearbeta. För enkla likhetsfall (till exempel föregående) kan du använda en karta. Du kan också lägga till specifika SQL-satser:

context.query.where('myfield eq ?', 'value');

Konfigurera en mjuk borttagning i en tabell

En mjuk borttagning tar inte bort poster. I stället markeras de som borttagna i databasen genom att den borttagna kolumnen anges till true. Azure Mobile Apps SDK tar automatiskt bort mjukt borttagna poster från resultat om inte Mobile Client SDK använder includeDeleted(). Om du vill konfigurera en tabell för mjuk borttagning anger du softDelete egenskapen i tabelldefinitionsfilen:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Turn on soft delete.
table.softDelete = true;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

Upprätta en mekanism för att ta bort poster permanent, till exempel ett klientprogram, ett webbjobb, en Azure-funktion eller ett anpassat API.

Seed din databas med data

När du skapar ett nytt program kanske du vill skapa en tabell med data. Du kan hämta data i tabelldefinitionens JavaScript-fil på följande sätt:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};
table.seed = [
    { text: 'Example 1', complete: false },
    { text: 'Example 2', complete: true }
];

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

Seeding av data sker bara när du har använt Azure Mobile Apps SDK för att skapa tabellen. Om tabellen redan finns i databasen matas inga data in i tabellen. Om det dynamiska schemat är aktiverat härleds schemat från de data som har hämtats.

Vi rekommenderar att du uttryckligen tables.initialize() anropar metoden för att skapa tabellen när tjänsten börjar köras.

Aktivera Swagger-stöd

Azure Mobile Apps levereras med inbyggd Swagger-support. Om du vill aktivera Swagger-stöd installerar du först swagger-ui som ett beroende:

npm install --save swagger-ui

Du kan sedan aktivera Swagger-stöd i Azure Mobile Apps-konstruktorn:

var mobile = azureMobileApps({ swagger: true });

Du vill förmodligen bara aktivera Swagger-stöd i utvecklingsversioner. Du kan aktivera Swagger-stöd i utveckling med hjälp av appinställningen NODE_ENV :

var mobile = azureMobileApps({ swagger: process.env.NODE_ENV !== 'production' });

Slutpunkten swagger finns på http:// yoursite.azurewebsites.net/swagger. Du kan komma åt Swagger-användargränssnittet via /swagger/ui slutpunkten. Om du väljer att kräva autentisering i hela programmet genererar Swagger ett fel. För bästa resultat väljer du att tillåta oautentiserade begäranden i inställningarna för Azure App Service-autentisering/auktorisering och sedan styra autentiseringen table.access med hjälp av egenskapen .

Du kan också lägga till swagger-alternativet i azureMobile.js filen om du bara vill ha Swagger-stöd för att utveckla lokalt.

Anpassade API:er

Utöver API:et för dataåtkomst via /tables slutpunkten kan Azure Mobile Apps tillhandahålla anpassad API-täckning. Anpassade API:er definieras på ett liknande sätt som tabelldefinitionerna och kan komma åt samma faciliteter, inklusive autentisering.

Definiera ett anpassat API

Anpassade API:er definieras på ungefär samma sätt som tabell-API:et:

1. Skapa en api katalog.
2. Skapa en API-definitions-JavaScript-fil i api katalogen.
3. Använd importmetoden för att importera api katalogen.

Här är api-prototypdefinitionen baserat på exemplet med basic-app som vi använde tidigare:

var express = require('express'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Import the custom API.
mobile.api.import('./api');

// Add the Mobile API so it is accessible as a Web API.
app.use(mobile);

// Start listening on HTTP
app.listen(process.env.PORT || 3000);

Nu ska vi ta ett exempel-API som returnerar serverdatumet med hjälp Date.now() av metoden . Här är api/date.js filen:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    });
};

module.exports = api;

Varje parameter är ett av standard-RESTful-verben: GET, POST, PATCH eller DELETE. Metoden är en expressJS-mellanprogramsfunktion som skickar nödvändiga utdata.

Kräv autentisering för åtkomst till ett anpassat API

Azure Mobile Apps SDK implementerar autentisering på samma sätt för både tables slutpunkten och anpassade API:er. Om du vill lägga till autentisering i API:et som utvecklades i föregående avsnitt lägger du till en access egenskap:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    });
};
// All methods must be authenticated.
api.access = 'authenticated';

module.exports = api;

Du kan också ange autentisering för specifika åtgärder:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    }
};
// The GET methods must be authenticated.
api.get.access = 'authenticated';

module.exports = api;

Samma token som används för tables slutpunkten måste användas för anpassade API:er som kräver autentisering.

Hantera stora filuppladdningar

Azure Mobile Apps SDK använder mellanprogrammet body-parser för att acceptera och avkoda brödtextinnehåll i din sändning. Du kan förkonfigurera body-parser för att acceptera större filuppladdningar:

var express = require('express'),
    bodyParser = require('body-parser'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Set up large body content handling.
app.use(bodyParser.json({ limit: '50mb' }));
app.use(bodyParser.urlencoded({ limit: '50mb', extended: true }));

// Import the custom API.
mobile.api.import('./api');

// Add the Mobile API so it is accessible as a Web API.
app.use(mobile);

// Start listening on HTTP.
app.listen(process.env.PORT || 3000);

Filen är base-64-kodad före överföring. Den här kodningen ökar storleken på den faktiska uppladdningen (och den storlek som du måste ta hänsyn till).

Köra anpassade SQL-instruktioner

Azure Mobile Apps SDK ger åtkomst till hela kontexten via begärandeobjektet. Du kan enkelt köra parametriserade SQL-instruktioner till den definierade dataprovidern:

var api = {
    get: function (request, response, next) {
        // Check for parameters. If not there, pass on to a later API call.
        if (typeof request.params.completed === 'undefined')
            return next();

        // Define the query. Anything that the mssql
        // driver can handle is allowed.
        var query = {
            sql: 'UPDATE TodoItem SET complete=@completed',
            parameters: [{
                completed: request.params.completed
            }]
        };

        // Execute the query. The context for Azure Mobile Apps is available through
        // request.azureMobile. The data object contains the configured data provider.
        request.azureMobile.data.execute(query)
        .then(function (results) {
            response.json(results);
        });
    }
};

api.get.access = 'authenticated';
module.exports = api;

Felsökning

Felsöka, diagnostisera och felsöka Azure Mobile Apps

Azure App Service innehåller flera felsöknings- och felsökningstekniker för Node.js-program. Information om hur du kommer igång med att felsöka serverdelen för Node.js Azure Mobile Apps finns i följande artiklar:

• Övervaka Azure App Service
• Aktivera diagnostikloggning i Azure App Service
• Felsöka nodprogram i Azure App Service

Node.js-program har åtkomst till en mängd olika verktyg för diagnostikloggar. Internt använder Azure Mobile Apps Node.js SDK [Winston] för diagnostikloggning. Loggning aktiveras automatiskt när du aktiverar felsökningsläge eller anger appinställningen MS_DebugMode till true i Azure-portalen. Genererade loggar visas i diagnostikloggarna i Azure-portalen.