Samouczek: wywoływanie interfejsu API programu Microsoft Graph w aplikacji demona konsoli Node.js

Artykuł
2025-04-10

Dotyczy: Dzierżawcy siły roboczej Biały okrąg z szarym symbolem X. dzierżawcy zewnętrzni (White circle with a gray X symbol.dowiedz się więcej)

W tym samouczku utworzysz aplikację działającą w tle dla konsoli, która wywołuje interfejs API Microsoft Graph, używając własnej tożsamości. Utworzona aplikacja demona używa biblioteki Microsoft Authentication Library (MSAL) do Node.js.

Postępuj zgodnie z krokami opisanymi w tym samouczku, aby:

Rejestrowanie aplikacji w witrynie Azure Portal
Tworzenie projektu aplikacji demona konsoli Node.js
Dodawanie logiki uwierzytelniania do aplikacji
Dodawanie szczegółów rejestracji aplikacji
Dodaj metodę do wywoływania API
Testowanie aplikacji

Wymagania wstępne

Node.js
Visual Studio Code lub inny edytor kodu

Rejestrowanie aplikacji

Najpierw wykonaj kroki opisane w temacie Rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft, aby zarejestrować aplikację.

Użyj następujących ustawień rejestracji aplikacji:

Nazwa: NodeDaemonApp (sugerowane)
Obsługiwane typy kont: konta tylko w tym katalogu organizacyjnym
Uprawnienia API: Microsoft API>Microsoft Graph>Uprawnienia aplikacji>User.Read.All
Wpis tajny klienta: ********* (zapisz tę wartość do użycia w późniejszym kroku — jest wyświetlany tylko raz)

Tworzenie projektu

Zacznij od utworzenia katalogu dla projektu samouczka o Node.js. Na przykład NodeDaemonApp.
W terminalu przejdź do utworzonego katalogu (katalogu głównego projektu), a następnie uruchom następujące polecenia:
```
npm init -y
npm install --save dotenv yargs axios @azure/msal-node
```
Następnie zmodyfikuj plik package.json w katalogu głównym projektu i dodaj prefiks main do wartości bin/, w następujący sposób:
```
"main": "bin/index.js",
```

Teraz utwórz katalog bin, a następnie wewnątrz bin dodaj następujący kod do nowego pliku o nazwie index.js:

#!/usr/bin/env node

// read in env settings
require('dotenv').config();

const yargs = require('yargs');

const fetch = require('./fetch');
const auth = require('./auth');

const options = yargs
    .usage('Usage: --op <operation_name>')
    .option('op', { alias: 'operation', describe: 'operation name', type: 'string', demandOption: true })
    .argv;

async function main() {
    console.log(`You have selected: ${options.op}`);

    switch (yargs.argv['op']) {
        case 'getUsers':

            try {
                // here we get an access token
                const authResponse = await auth.getToken(auth.tokenRequest);

                // call the web API with the access token
                const users = await fetch.callApi(auth.apiConfig.uri, authResponse.accessToken);

                // display result
                console.log(users);
            } catch (error) {
                console.log(error);
            }

            break;
        default:
            console.log('Select a Graph operation first');
            break;
    }
};

main();

Utworzony plik index.js odwołuje się do dwóch innych modułów węzłów, które utworzysz w następnej kolejności:

auth.js — używa MSAL Node do uzyskiwania tokenów dostępu z platformy tożsamości Microsoft.
fetch.js — żąda danych z interfejsu API programu Microsoft Graph przez uwzględnienie tokenów dostępu (uzyskanych w auth.js) w żądaniach HTTP do interfejsu API.

Na końcu samouczka struktura plików i katalogów projektu powinna wyglądać mniej więcej tak:

NodeDaemonApp/
├── bin
│   ├── auth.js
│   ├── fetch.js
│   ├── index.js
├── package.json
└── .env

Dodawanie logiki uwierzytelniania

W katalogu bin dodaj następujący kod do nowego pliku o nazwie auth.js. Kod w auth.js uzyskuje token dostępu z platformy tożsamości Microsoft w celu dołączania do żądań interfejsu API Microsoft Graph.

const msal = require('@azure/msal-node');

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + '/' + process.env.TENANT_ID,
        clientSecret: process.env.CLIENT_SECRET,
    }
};

/**
 * With client credentials flows permissions need to be granted in the portal by a tenant administrator.
 * The scope is always in the format '<resource>/.default'. For more, visit:
 * https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
 */
const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '/.default'],
};

const apiConfig = {
    uri: process.env.GRAPH_ENDPOINT + '/v1.0/users',
};

/**
 * Initialize a confidential client application. For more info, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-confidential-client-application.md
 */
const cca = new msal.ConfidentialClientApplication(msalConfig);

/**
 * Acquires token with client credentials.
 * @param {object} tokenRequest
 */
async function getToken(tokenRequest) {
    return await cca.acquireTokenByClientCredential(tokenRequest);
}

module.exports = {
    apiConfig: apiConfig,
    tokenRequest: tokenRequest,
    getToken: getToken
};

W powyższym fragmencie kodu najpierw tworzymy obiekt konfiguracji (msalConfig) i używamy go do zainicjowania aplikacji MSAL ConfidentialClientApplication. Następnie utworzymy metodę uzyskiwania tokenów za pośrednictwem danych uwierzytelniających klienta i na koniec uwidaczniamy ten moduł, aby można było uzyskać do niego dostęp przez main.js. Parametry konfiguracji w tym module są pobierane z pliku środowiska, który zostanie utworzony w następnym kroku.

Dodawanie szczegółów rejestracji aplikacji

Utwórz plik środowiska do przechowywania szczegółów rejestracji aplikacji, które będą używane podczas uzyskiwania tokenów. W tym celu utwórz plik o nazwie env w folderze głównym przykładu (NodeDaemonApp) i dodaj następujący kod:

# Credentials
TENANT_ID=Enter_the_Tenant_Id_Here
CLIENT_ID=Enter_the_Application_Id_Here
CLIENT_SECRET=Enter_the_Client_Secret_Here

# Endpoints
AAD_ENDPOINT=Enter_the_Cloud_Instance_Id_Here/
GRAPH_ENDPOINT=Enter_the_Graph_Endpoint_Here/

Wypełnij te szczegóły wartościami uzyskanymi w portalu rejestracji aplikacji platformy Azure:

Enter_the_Tenant_Id_here powinien być jednym z następujących elementów:
- Jeśli aplikacja obsługuje konta w tym katalogu organizacyjnym, zastąp tę wartość identyfikatorem Identyfikator dzierżawy lub Nazwa dzierżawy. Na przykład contoso.microsoft.com.
- Jeśli aplikacja obsługuje konta w dowolnym katalogu organizacyjnym, zastąp tę wartość wartością organizations.
- Jeśli aplikacja obsługuje konta w dowolnym katalogu organizacyjnym i osobistych kontach Microsoft, zastąp tę wartość wartością common.
- Aby ograniczyć obsługę tylko do osobistych kont Microsoft, zastąp tę wartość wartością consumers.
Enter_the_Application_Id_Here : identyfikator aplikacji (klienta) zarejestrowanej aplikacji.
Enter_the_Cloud_Instance_Id_Here: instancja chmury Azure, w której zarejestrowano aplikację.
- W przypadku głównej (lub globalnej) chmury platformy Azure wprowadź .https://login.microsoftonline.com
- W przypadku chmur krajowych (na przykład w Chinach) można znaleźć odpowiednie wartości w chmurach krajowych.
Enter_the_Graph_Endpoint_Here to wystąpienie interfejsu API Microsoft Graph, z którym aplikacja powinna się komunikować.
- W przypadku globalnego punktu końcowego interfejsu API programu Microsoft Graph, zastąp oba wystąpienia tego ciągu tekstowego nowym ciągiem .
- Aby uzyskać informacje o punktach końcowych we wdrożeniach chmury krajowej, zobacz Wdrożenia chmury krajowej w dokumentacji programu Microsoft Graph.

Dodaj metodę do wywoływania API

W folderze bin utwórz inny plik o nazwie fetch.js i dodaj następujący kod do wykonywania wywołań REST do interfejsu API programu Microsoft Graph:

const axios = require('axios');

/**
 * Calls the endpoint with authorization bearer token.
 * @param {string} endpoint
 * @param {string} accessToken
 */
async function callApi(endpoint, accessToken) {

    const options = {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    };

    console.log('request made to web API at: ' + new Date().toString());

    try {
        const response = await axios.get(endpoint, options);
        return response.data;
    } catch (error) {
        console.log(error)
        return error;
    }
};

module.exports = {
    callApi: callApi
};

callApi W tym miejscu metoda służy do tworzenia żądania HTTP GET względem chronionego zasobu, który wymaga tokenu dostępu. Następnie żądanie zwraca zawartość do wywołującego. Ta metoda dodaje uzyskany token w nagłówku HTTP Authorization. Chroniony zasób to punkt końcowy użytkowników w interfejsie API Microsoft Graph, który pokazuje użytkowników w dzierżawie, gdzie zarejestrowano tę aplikację.

Testowanie aplikacji

Ukończono tworzenie aplikacji i teraz możesz przystąpić do testowania funkcjonalności aplikacji.

Uruchom aplikację demona konsoli Node.js, uruchamiając następujące polecenie z poziomu katalogu głównego folderu projektu:

node . --op getUsers

Powinno to spowodować odpowiedź w formacie JSON z interfejsu API programu Microsoft Graph i powinna zostać wyświetlona tablica obiektów użytkownika w konsoli programu :

You have selected: getUsers
request made to web API at: Fri Jan 22 2021 09:31:52 GMT-0800 (Pacific Standard Time)
{
    '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users',
    value: [
        {
            displayName: 'Adele Vance'
            givenName: 'Adele',
            jobTitle: 'Retail Manager',
            mail: 'AdeleV@msaltestingjs.onmicrosoft.com',
            mobilePhone: null,
            officeLocation: '18/2111',
            preferredLanguage: 'en-US',
            surname: 'Vance',
            userPrincipalName: 'AdeleV@msaltestingjs.onmicrosoft.com',
            id: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'
        }
    ]
}

Interfejs wiersza polecenia wyświetlający odpowiedź programu Graph

Jak działa aplikacja

Ta aplikacja używa poświadczeń klienta protokołu OAuth 2.0. Ten typ uprawnień jest często używany do interakcji między serwerami, które muszą działać w tle bez natychmiastowej interakcji z użytkownikiem. Przepływ udzielania poświadczeń umożliwia usłudze internetowej (poufnemu klientowi) używanie własnych poświadczeń zamiast personifikowania użytkownika w celu uwierzytelniania podczas wywoływania innej usługi internetowej. Typ aplikacji obsługiwanych w tym modelu uwierzytelniania to zwykle demony lub konta usług.

Zakres żądania przepływu poświadczeń klienta to nazwa zasobu, po którym następuje /.default. Notacja ta informuje Microsoft Entra ID o użyciu uprawnień aplikacyjnych zadeklarowanych statycznie podczas rejestracji aplikacji. Ponadto te uprawnienia interfejsu API muszą zostać przyznane przez administratora dzierżawy.

Następne kroki

Jeśli chcesz dowiedzieć się więcej na temat tworzenia aplikacji demona Node.js na platformie tożsamości Microsoft, zobacz naszą wieloczęściową serię scenariuszy:

Scenariusz: aplikacja demona

Udostępnij za pośrednictwem