Приступая к разработке для Azure CDNGet started with Azure CDN development

С помощью пакета SDK Azure CDN для Node.js можно автоматизировать создание профилей и конечных точек CDN и управление ими.You can use the Azure CDN SDK for Node.js to automate creation and management of CDN profiles and endpoints. В этом руководстве описывается создание простого консольного приложения Node.js с примерами некоторых доступных операций.This tutorial walks through the creation of a simple Node.js console application that demonstrates several of the available operations. Это руководство не содержит подробные сведения обо всех свойствах пакета Azure CDN SDK для Node.js.This tutorial is not intended to describe all aspects of the Azure CDN SDK for Node.js in detail.

Для работы с этим учебником должен быть установлен и настроен компонент Node.js 4.x.x или более поздней версии.To complete this tutorial, you should already have Node.js 4.x.x or higher installed and configured. Для создания приложения Node.js вы можете использовать любой текстовый редактор.You can use any text editor you want to create your Node.js application. Например, в этом учебнике используется Visual Studio Code.To write this tutorial, I used Visual Studio Code.

Совет

Завершенный проект из этого учебника доступен для скачивания на сайте MSDN.

Технические условияPrerequisites

Перед созданием кода управления CDN необходимо выполнить определенную подготовку, чтобы код мог взаимодействовать с Azure Resource Manager.Before writing CDN management code, you must do some preparation to enable the code to interact with the Azure Resource Manager. Для этого сделайте следующее:To do this preparation, you need to:

  • Создайте группу ресурсов для профиля CDN, который мы создадим в этом руководстве.Create a resource group to contain the CDN profile created in this tutorial
  • Настройте Azure Active Directory, чтобы выполнить проверку подлинности приложения.Configure Azure Active Directory to provide authentication for the application
  • Примените разрешения для группы ресурсов, чтобы только авторизованные пользователи могли с помощью клиента Azure AD взаимодействовать с профилем CDN.Apply permissions to the resource group so that only authorized users from your Azure AD tenant can interact with the CDN profile

Создание группы ресурсовCreating the resource group

  1. Войдите на портал Azure.Sign in to the Azure Portal.

  2. Щелкните Создать ресурс.Click Create a resource.

  3. Найдите Группу ресурсов, а затем в ее области щелкните Создать.Search for Resource group and in the Resource group pane, click Create.

    Создание новой группы ресурсов

  4. Назовите группу ресурсов CdnConsoleTutorial.Name your resource group CdnConsoleTutorial. Выберите свою подписку и ближайшее расположение.Select your subscription and choose a location near you. При желании установите флажок Закрепить на панели мониторинга, чтобы закрепить группу ресурсов на панели мониторинга на портале.If you wish, you can click the Pin to dashboard checkbox to pin the resource group to the dashboard in the portal. Так ее будет проще найти.Pinning makes it easier to find later. Выберите необходимые параметры, а затем нажмите кнопку Создать.After you've made your selections, click Create.

    Присвоение имени группе ресурсов

  5. Если вы не закрепили созданную группу ресурсов на панели мониторинга, щелкните Обзор, а затем — Группы ресурсов, чтобы найти группу.After the resource group is created, if you didn't pin it to your dashboard, you can find it by clicking Browse, then Resource Groups. Щелкните группу ресурсов, чтобы открыть ее.To open it, click the resource group. Запишите идентификатор подписки.Make a note of your Subscription ID. Он понадобится нам позже.We need it later.

    Присвоение имени группе ресурсов

Создание приложения Azure AD и применение разрешенийCreating the Azure AD application and applying permissions

Существует два подхода к проверке подлинности приложений с Azure Active Directory: Отдельных пользователей или субъекта-службы.There are two approaches to app authentication with Azure Active Directory: Individual users or a service principal. Субъект-служба аналогичен учетной записи службы в Windows.A service principal is similar to a service account in Windows. Вместо того, чтобы предоставить разрешения на взаимодействие с профилями CDN определенному пользователю, мы предоставляем их субъекту-службе.Instead of granting a particular user permissions to interact with the CDN profiles, permissions are instead granted to the service principal. Субъекты-службы обычно используются для автоматических, неинтерактивных процессов.Service principals are typically used for automated, non-interactive processes. Несмотря на то, что в этом учебнике создается интерактивное приложение консоли, мы будем использовать субъект-службу.Even though this tutorial is writing an interactive console app, we'll focus on the service principal approach.

Создание субъекта-службы состоит из нескольких шагов, включая создание приложения Azure Active Directory.Creating a service principal consists of several steps, including creating an Azure Active Directory application. Для этого воспользуйтесь инструкциями из этого руководства.To create it, we're going to follow this tutorial.

Важно!

Обязательно выполните все шаги, приведенные в связанном руководстве.Be sure to follow all the steps in the linked tutorial. Важно выполнить все в точности, как описано.It is important that you complete it exactly as described. Обязательно запишите идентификатор клиента, доменное имя клиента (обычно это домен .onmicrosoft.com, если вы не указали личный домен), идентификатор клиента и ключ проверки подлинности клиента, так как эти данные понадобятся позже.Make sure to note your tenant ID, tenant domain name (commonly a .onmicrosoft.com domain unless you've specified a custom domain), client ID, and client authentication key, as we need this information later. Следует ответственно отнестись к защите идентификатора клиента и ключа проверки подлинности клиента, так как с помощью этих учетных данных любой пользователь может выполнять операции в качестве субъекта-службы.Be careful to guard your client ID and client authentication key, as these credentials can be used by anyone to execute operations as the service principal.

На шаге "Настройка мультитенантного приложения" выберите Нет.When you get to the step named Configure multi-tenant application, select No.

На шаге Назначение роли приложению укажите группу ресурсов CdnConsoleTutorial, созданную ранее, но вместо роли Читатель назначьте роль Участник профиля CDN.When you get to the step Assign the application to a role, use the resource group created earlier, CdnConsoleTutorial, but instead of the Reader role, assign the CDN Profile Contributor role. Назначьте приложению роль Участник профиля CDN для группы ресурсов, а затем вернитесь к этому руководству.After you assign the application the CDN Profile Contributor role on your resource group, return to this tutorial.

Когда вы создадите субъект-службу и назначите роль Участник профиля CDN, колонка Пользователи вашей группы ресурсов будет выглядеть так.Once you've created your service principal and assigned the CDN Profile Contributor role, the Users blade for your resource group should look similar to the following image.

Колонка "Пользователи"

Интерактивная аутентификация пользователейInteractive user authentication

Если вместо субъекта-службы требуется настроить интерактивную аутентификацию отдельных пользователей, то необходимые действия будут похожи на настройку субъекта-службы.If, instead of a service principal, you'd rather have interactive individual user authentication, the process is similar to that for a service principal. На самом деле необходимо выполнить ту же самую процедуру, но с незначительными изменениями.In fact, you need to follow the same procedure, but make a few minor changes.

Важно!

Выполните следующие шаги, только если решили использовать аутентификацию отдельных пользователей, а не субъект-службу.Only follow these next steps if you are choosing to use individual user authentication instead of a service principal.

  1. Создавая приложение, вместо значения Веб-приложение выберите Собственное приложение.When creating your application, instead of Web Application, choose Native application.

    Собственное приложение

  2. На следующей странице вам будет предложено ввести универсальный код ресурса (URI) перенаправления.On the next page, you are prompted for a redirect URI. Универсальный код ресурса (URI) не будет проверяться, но запомните, что вы ввели.The URI won't be validated, but remember what you entered. Он понадобится вам позже.You need it later.

  3. Не нужно создавать ключ проверки подлинности клиента.There is no need to create a client authentication key.

  4. Вместо того, чтобы назначить роль Участник роли CDN субъекту-службе, мы назначим ее отдельным пользователям или группам.Instead of assigning a service principal to the CDN Profile Contributor role, we're going to assign individual users or groups. Из этого примера понятно, что пользователю CDN Demo User назначена роль CDN Profile Contributor (Участник профиля CDN).In this example, you can see that I've assigned CDN Demo User to the CDN Profile Contributor role.

    Индивидуальный доступ пользователей

Создание проекта и добавление зависимостей NPMCreate your project and add NPM dependencies

Создав группу ресурсов для профилей CDN и назначив приложению Azure AD разрешения для управления профилями CDN и конечными точками в этой группе, мы можем приступить к созданию своего приложения.Now that we've created a resource group for our CDN profiles and given our Azure AD application permission to manage CDN profiles and endpoints within that group, we can start creating our application.

Создайте папку для хранения приложения.Create a folder to store your application. С помощью консоли, в которой средства Node.js включены в текущий путь, перейдите в эту новую папку и инициализируйте проект с помощью следующей команды:From a console with the Node.js tools in your current path, set your current location to this new folder and initialize your project by executing:

npm init

Вам будет предложено ответить на ряд вопросов для инициализации проекта.You will then be presented a series of questions to initialize your project. В качестве точки входав этом руководстве используется app.js.For entry point, this tutorial uses app.js. В приведенном ниже примере вы можете увидеть значения других параметров.You can see my other choices in the following example.

Выходные данные NPM

Теперь наш проект будет инициализирован с помощью файла packages.json .Our project is now initialized with a packages.json file. В проекте будут использоваться некоторые библиотеки Azure, содержащиеся в пакетах NPM.Our project is going to use some Azure libraries contained in NPM packages. Мы будем использовать клиентскую среду Azure для Node.js (ms-rest-azure) и клиентскую библиотеку Azure CDN для Node.js (azure-arm-cd).We'll use the Azure Client Runtime for Node.js (ms-rest-azure) and the Azure CDN Client Library for Node.js (azure-arm-cd). Давайте добавим эти зависимости в проект.Let's add those to the project as dependencies.

npm install --save ms-rest-azure
npm install --save azure-arm-cdn

Когда установка этих пакетов завершится, файл package.json должен выглядеть примерно так (номер версии может отличаться):After the packages are done installing, the package.json file should look similar to this example (version numbers may differ):

{
  "name": "cdn_node",
  "version": "1.0.0",
  "description": "Azure CDN Node.js tutorial project",
  "main": "app.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Cam Soper",
  "license": "MIT",
  "dependencies": {
    "azure-arm-cdn": "^0.2.1",
    "ms-rest-azure": "^1.14.4"
  }
}

И, наконец, создайте с помощью текстового редактора пустой текстовый файл и сохраните его с именем app.jsв корневой папке проекта.Finally, using your text editor, create a blank text file and save it in the root of our project folder as app.js. Теперь мы готовы приступить к написанию кода.We're now ready to begin writing code.

Требования, константы, проверка подлинности и структураRequires, constants, authentication, and structure

Давайте откроем файл app.js в редакторе и создадим базовую структуру нашей программы.With app.js open in our editor, let's get the basic structure of our program written.

  1. В начале файла добавьте строки required для всех наших пакетов NPM:Add the "requires" for our NPM packages at the top with the following:

    var msRestAzure = require('ms-rest-azure');
    var cdnManagementClient = require('azure-arm-cdn');
    
  2. Необходимо определить несколько констант, которые будут использоваться нашими методами.We need to define some constants our methods will use. Добавьте следующий код.Add the following. Обязательно замените заполнители, включая <угловые скобки>, собственными значениями.Be sure to replace the placeholders, including the <angle brackets>, with your own values as needed.

    //Tenant app constants
    const clientId = "<YOUR CLIENT ID>";
    const clientSecret = "<YOUR CLIENT AUTHENTICATION KEY>"; //Only for service principals
    const tenantId = "<YOUR TENANT ID>";
    
    //Application constants
    const subscriptionId = "<YOUR SUBSCRIPTION ID>";
    const resourceGroupName = "CdnConsoleTutorial";
    const resourceLocation = "<YOUR PREFERRED AZURE LOCATION, SUCH AS Central US>";
    
  3. Далее мы создадим клиент управления CDN и передадим ему наши учетные данные.Next, we'll instantiate the CDN management client and give it our credentials.

    var credentials = new msRestAzure.ApplicationTokenCredentials(clientId, tenantId, clientSecret);
    var cdnClient = new cdnManagementClient(credentials, subscriptionId);
    

    Если вы используете аутентификацию отдельных пользователей, эти две строки будут выглядеть немного иначе.If you are using individual user authentication, these two lines will look slightly different.

    Важно!

    Используйте приведенный пример кода, только если решили использовать аутентификацию отдельных пользователей, а не субъект-службу. Следите за тем, чтобы ваши учетные данные пользователя хранились в секрете.

    var credentials = new msRestAzure.UserTokenCredentials(clientId, 
        tenantId, '<username>', '<password>', '<redirect URI>');
    var cdnClient = new cdnManagementClient(credentials, subscriptionId);
    

    Не забудьте заменить правильными данными все элементы в <угловых скобках>.Be sure to replace the items in <angle brackets> with the correct information. Вместо <redirect URI>укажите универсальный код ресурса (URI) перенаправления, который вы ввели при регистрации приложения в Azure AD.For <redirect URI>, use the redirect URI you entered when you registered the application in Azure AD.

  4. Консольное приложение Node.js будет принимать некоторые параметры командной строки.Our Node.js console application is going to take some command-line parameters. Давайте добавим проверку того, что передан хотя бы один параметр.Let's validate that at least one parameter was passed.

    //Collect command-line parameters
    var parms = process.argv.slice(2);
    
    //Do we have parameters?
    if(parms == null || parms.length == 0)
    {
        console.log("Not enough parameters!");
        console.log("Valid commands are list, delete, create, and purge.");
        process.exit(1);
    }
    
  5. Теперь мы добрались до основной части нашей программы — мы будем запускать другие функции в зависимости от того, какие параметры были переданы.That brings us to the main part of our program, where we branch off to other functions based on what parameters were passed.

    switch(parms[0].toLowerCase())
    {
        case "list":
            cdnList();
            break;
    
        case "create":
            cdnCreate();
            break;
    
        case "delete":
            cdnDelete();
            break;
    
        case "purge":
            cdnPurge();
            break;
    
        default:
            console.log("Valid commands are list, delete, create, and purge.");
            process.exit(1);
    }
    
  6. Также мы будем проверять, передано ли нужное число параметров; если параметры имеют неправильный формат, будут отображены подсказки.At several places in our program, we'll need to make sure the right number of parameters were passed in and display some help if they don't look correct. Давайте создадим для этого функции.Let's create functions to do that.

    function requireParms(parmCount) {
        if(parms.length < parmCount) {
            usageHelp(parms[0].toLowerCase());
            process.exit(1);
        }
    }
    
    function usageHelp(cmd) {
        console.log("Usage for " + cmd + ":");
        switch(cmd)
        {
            case "list":
                console.log("list profiles");
                console.log("list endpoints <profile name>");
                break;
    
            case "create":
                console.log("create profile <profile name>");
                console.log("create endpoint <profile name> <endpoint name> <origin hostname>");
                break;
    
            case "delete":
                console.log("delete profile <profile name>");
                console.log("delete endpoint <profile name> <endpoint name>");
                break;
    
            case "purge":
                console.log("purge <profile name> <endpoint name> <path>");
                break;
    
            default:
                console.log("Invalid command.");
        }
    }
    
  7. Кроме того, мы будем использовать на клиенте управления CDN асинхронные функции, поэтому нам нужен метод для обратного вызова после завершения их работы.Finally, the functions we'll be using on the CDN management client are asynchronous, so they need a method to call back when they're done. Давайте создадим такой метод, который будет отображать данные, полученные от клиента управления CDN (если они есть) и корректно завершать работу программы.Let's make one that can display the output from the CDN management client (if any) and exit the program gracefully.

    function callback(err, result, request, response) {
        if (err) {
            console.log(err);
            process.exit(1);
        } else {
            console.log((result == null) ? "Done!" : result);
            process.exit(0);
        }
    }
    

Теперь базовая структура программы полностью готова, и мы можем создать функции, вызываемые на основе полученных параметров.Now that the basic structure of our program is written, we should create the functions called based on our parameters.

Вывод списка профилей CDN и конечных точекList CDN profiles and endpoints

Давайте начнем с кода, который выводит список существующих профилей и конечных точек.Let's start with code to list our existing profiles and endpoints. Я дополню код комментариями с описанием синтаксиса, чтобы было понятно, для чего предназначен каждый параметр.My code comments provide the expected syntax so we know where each parameter goes.

// list profiles
// list endpoints <profile name>
function cdnList(){
    requireParms(2);
    switch(parms[1].toLowerCase())
    {
        case "profiles":
            console.log("Listing profiles...");
            cdnClient.profiles.listByResourceGroup(resourceGroupName, callback);
            break;

        case "endpoints":
            requireParms(3);
            console.log("Listing endpoints...");
            cdnClient.endpoints.listByProfile(parms[2], resourceGroupName, callback);
            break;

        default:
            console.log("Invalid parameter.");
            process.exit(1);
    }
}

Создание профилей CDN и конечных точекCreate CDN profiles and endpoints

Теперь давайте напишем функцию для создания профилей и конечных точек.Next, we'll write the functions to create profiles and endpoints.

function cdnCreate() {
    requireParms(2);
    switch(parms[1].toLowerCase())
    {
        case "profile":
            cdnCreateProfile();
            break;

        case "endpoint":
            cdnCreateEndpoint();
            break;

        default:
            console.log("Invalid parameter.");
            process.exit(1);
    }
}

// create profile <profile name>
function cdnCreateProfile() {
    requireParms(3);
    console.log("Creating profile...");
    var standardCreateParameters = {
        location: resourceLocation,
        sku: {
            name: 'Standard_Verizon'
        }
    };

    cdnClient.profiles.create(parms[2], standardCreateParameters, resourceGroupName, callback);
}

// create endpoint <profile name> <endpoint name> <origin hostname>        
function cdnCreateEndpoint() {
    requireParms(5);
    console.log("Creating endpoint...");
    var endpointProperties = {
        location: resourceLocation,
        origins: [{
            name: parms[4],
            hostName: parms[4]
        }]
    };

    cdnClient.endpoints.create(parms[3], endpointProperties, parms[2], resourceGroupName, callback);
}

Очистка конечной точкиPurge an endpoint

Одной из задач, которая может выполняться в программе после создания конечной точки, является очистка содержимого в ней.Assuming the endpoint has been created, one common task that we might want to perform in our program is purging content in our endpoint.

// purge <profile name> <endpoint name> <path>
function cdnPurge() {
    requireParms(4);
    console.log("Purging endpoint...");
    var purgeContentPaths = [ parms[3] ];
    cdnClient.endpoints.purgeContent(parms[2], parms[1], resourceGroupName, purgeContentPaths, callback);
}

Удаление профилей CDN и конечных точекDelete CDN profiles and endpoints

Наша последняя функция будет удалять конечные точки и профили.The last function we will include deletes endpoints and profiles.

function cdnDelete() {
    requireParms(2);
    switch(parms[1].toLowerCase())
    {
        // delete profile <profile name>
        case "profile":
            requireParms(3);
            console.log("Deleting profile...");
            cdnClient.profiles.deleteIfExists(parms[2], resourceGroupName, callback);
            break;

        // delete endpoint <profile name> <endpoint name>
        case "endpoint":
            requireParms(4);
            console.log("Deleting endpoint...");
            cdnClient.endpoints.deleteIfExists(parms[3], parms[2], resourceGroupName, callback);
            break;

        default:
            console.log("Invalid parameter.");
            process.exit(1);
    }
}

Запуск программыRunning the program

Теперь мы можем выполнить нашу программу Node.js в любом удобном отладчике или консоли.We can now execute our Node.js program using our favorite debugger or at the console.

Совет

Если вы используете в качестве отладчика Visual Studio Code, вам потребуется настроить среду для передачи параметров командной строки. Для этой цели в Visual Studio Code используется файл launch.json. Найдите в нем свойство args и добавьте массив строковых значений со своими параметрами следующего вида: "args": ["list", "profiles"].

Давайте начнем с получения списка профилей.Let's start by listing our profiles.

Список профилей

Мы получили пустой массив.We got back an empty array. Так и должно быть, ведь в нашей группе ресурсов пока нет профилей.Since we don't have any profiles in our resource group, that's expected. Теперь давайте создадим профиль.Let's create a profile now.

Создание профиля

Теперь мы добавим конечную точку.Now, let's add an endpoint.

Создать конечную точку

И в завершение давайте удалим профиль.Finally, let's delete our profile.

Удаление профиля

Следующие шагиNext Steps

Чтобы просмотреть описываемый в этом руководстве готовый проект, скачайте пример.To see the completed project from this walkthrough, download the sample.

Справочную информацию о пакете SDK Azure CDN для Node.js вы найдете здесь.To see the reference for the Azure CDN SDK for Node.js, view the reference.

Чтобы получить дополнительную документацию о пакете SDK Azure для Node.js, откройте полный справочник.To find additional documentation on the Azure SDK for Node.js, view the full reference.

Управление ресурсами CDN с помощью PowerShell.Manage your CDN resources with PowerShell.