Это делает URL-адрес для выборки объекта pet с идентификатором 1: https://petstore.swagger.io/v2/pet/1

В документации SWAGGER REST API обычно отображается базовый URL-адрес в верхней части страницы.

Теперь начнем с PowerShell. Откройте окно терминала и введите:

Поскольку в ответе от сервера возвращается тип содержимого «application/json» используется метод Invoke-RestMethod, который автоматически преобразует возвращаемый JSON в объект.

Ошибка 404 Not found, как правило, означает, что объект не найден или URL-адрес введен неправильно.

Итак, мы выполнили первый вызов REST API. Но возможности метода GET для получения данных довольно ограничены, так что давайте создадим что-нибудь с помощью метода POST.

Создание объекта методом POST

Метод POST чаще всего используется для создания, например, пользователей или записей и т.д. Запрос POST отправляет BODY, содержащий информацию, конечной точке REST, обычно в формате JSON, но он также может быть в виде формы с кодировкой URL.

Вы узнаете, как создать объект JSON, который можно отправить в конечную точку/pet.

Можно увидеть, как должен выглядеть JSON, если развернуть строку POST/pet в документации.

Начнем с создания хэштаблицы, который можно преобразовать в объект JSON. Raw JSON следует избегать в скриптах PowerShell, поскольку он ограничивает его возможности.

Если вам трудно создать хештаблицу, который преобразуется в нужный JSON, установите модуль PsdKit и используйте команду $ JsonString | ThreadTo-Psd

Теперь имеется хэш-таблица, которую можно преобразовать в строку JSON и POST в конечную точку/pet:

При создании объекта он обычно получает созданный для подтверждения объект. Использование DELETE. Метод DELETE используется для удаления данных, а применение очень схоже с методом GET.

Только убедитесь, что не удалите ничего важного

Использование PUT

Метод PUT используется для обновления данных. Это делается аналогично методу POST путем представления полного или частичного объекта JSON:

Обычно API REST возвращает объект JSON с использованными и/или обновленными данными. Можно увидеть, что объект был обновлен с помощью метода GET:

Создание функций

Писать эти команды каждый раз вручную может стать довольно утомительным и на самом деле не масштабируемым. Если мы вызываем конечную точку несколько раз, то лучше создать для нее функцию. Это довольно просто и нужно написать всего несколько строк:

После создания функции ее можно вызвать в сценарии:

Это можно сделать и для метода POST для создания нового объекта pet в Petstore:

И вызов этой функции PowerShell намного упрощает задачу:

Возможно, что многие модули, которые вы ежедневно используете, состоят из функций, который за кулисами используют REST API.

Заключение

Обучение работы с REST API, главным образом основано на чтении документации. Мы использовали документацию на основе SWAGGER в этом посте, так как она представляет, как могут выглядеть другие стили документации.

Кроме того, преобразование вызовов API в функцию может сэкономить много времени, упростить работу и очистить сценарии.

Глава 1. Начало работы с PowerShell Chapter 1 — Getting Started with PowerShell

Я часто вижу, что выступающие на конференциях и собраниях групп пользователей уже работают с PowerShell, когда демонстрируют презентации начального уровня. I often find that presenters at conferences and user group meetings already have PowerShell running when they start entry-level presentations. Эта книга начинается с ответов на вопросы, которые задавали участники мероприятий, ранее не использовавшие PowerShell. This book begins by answering the questions I’ve heard attendees who haven’t previously used PowerShell ask in those sessions.

В частности, эта глава посвящена поиску и запуску PowerShell, а также решению некоторых первоначальных проблем, с которыми сталкиваются новые пользователи при работе с PowerShell. Specifically, this chapter focuses on finding and launching PowerShell, and solving some of the initial pain points that new users experience with PowerShell. Обязательно ознакомьтесь с примерами, приведенными в этой главе, и выполните их на компьютере Windows 10 с лабораторной средой. Be sure to follow along and walk through the examples shown in this chapter on your Windows 10 lab environment computer.

Что нужно, чтобы начать работу с PowerShell? What do I need to get started with PowerShell?

Все современные версии операционных систем Windows поставляются с установленной оболочкой PowerShell. All modern versions of Windows operating systems ship with PowerShell installed. Если вы используете версию, предшествующую 5.1, следует установить последнюю версию. If you’re running a version older than 5.1, you should install the latest version.

• Сведения об обновлении до версии PowerShell 5.1 см. в разделе Обновление существующей версии Windows PowerShell. To upgrade to Windows PowerShell 5.1, see Upgrading existing Windows PowerShell
• Сведения об установке последней версии PowerShell см. в статье Installing Windows PowerShell. To install the latest version of PowerShell, see Installing PowerShell

Где найти PowerShell? Where do I find PowerShell?

Самый простой способ найти PowerShell в Windows 10 — ввести PowerShell в строке поиска, как показано на рис. 1-1. The easiest way to find PowerShell on Windows 10 is to type PowerShell into the search bar as shown in Figure 1-1.

Обратите внимание, что на рис. 1-1 показаны четыре разных ярлыка для PowerShell. Notice that four different shortcuts for PowerShell are shown in Figure 1-1. Компьютер, используемый в демонстрационных целях в этой книге, работает под управлением 64-разрядной версии Windows 10, поэтому существует 64-разрядная версия консоли PowerShell и PowerShell ISE (интегрированной среды сценариев) и 32-разрядная версия каждой из них (обозначена суффиксом (x86) на ярлыках). The computer used for demonstration purposes in this book is running the 64-bit version of Windows 10 so there’s a 64-bit version of the PowerShell console and the PowerShell ISE (Integrated Scripting Environment), and a 32-bit version of each one as denoted by the (x86) suffix on the shortcuts. Если вы работаете с 32-разрядной версией Windows 10, у вас будет только два ярлыка. If you happen to be running a 32-bit version of Windows 10, you’ll only have two shortcuts. У этих элементов нет суффикса (x86), но они являются 32-разрядными версиями. Those items don’t have the (x86) suffix, but are 32-bit versions. Если у вас установлена 64-разрядная операционная система, рекомендуется запускать 64-разрядную версию PowerShell, только если вас нет особой причины для запуска 32-разрядной версии. If you have a 64-bit operating system, my recommendation is to run the 64-bit version of PowerShell unless you have a specific reason for running the 32-bit version.

Сведения о запуске PowerShell в других версиях Windows см. в статье Запуск Windows PowerShell. For information about starting PowerShell on other versions of Windows, see Starting Windows PowerShell.

Как запустить PowerShell? How do I launch PowerShell?

В производственной среде предприятия, которую я поддерживаю, я работаю с тремя разными учетными записями пользователей Active Directory. In the production enterprise environments that I support, I use three different Active Directory user accounts. В лабораторной среде в этой книге используются зеркальные экземпляры этих учетных записей. I’ve mirrored those accounts in the lab environment used in this book. Я вошел на компьютер с Windows 10 в качестве пользователя домена, который не является администратором домена или локальным администратором. I log into the Windows 10 computer as a domain user who is not a domain or local administrator.

Я запустил консоль PowerShell, щелкнув ярлык Windows PowerShell, как показано на рис. 1-1. I’ve launched the PowerShell console by clicking on the «Windows PowerShell» shortcut as shown in Figure 1-1.

Обратите внимание, что в строке заголовка консоли PowerShell указано «Windows PowerShell», как показано на рис. 1-4. Notice that the title bar of the PowerShell console says «Windows PowerShell» as shown in Figure 1-4. Некоторые команды выполняются нормально, но PowerShell не поддерживает управление доступом пользователей (UAC). Some commands run fine, but PowerShell can’t participate in User Access Control (UAC). Это означает, что оболочка не может запрашивать повышение прав для задач, требующих утверждения администратором. That means it’s unable to prompt for elevation for tasks that require the approval of an administrator. Выдается следующее сообщение об ошибке. The following error message is generated:

Решение этой проблемы заключается в запуске PowerShell от имени пользователя домена, который является локальным администратором. The solution to this problem is to run PowerShell as a domain user who is a local administrator. Именно так настроена моя вторая учетная запись пользователя домена. This is how my second domain user account is configured. При использовании принципа наименьших привилегий эта учетная запись не должна быть администратором домена или иметь любые повышенные привилегии в домене. Using the principle of least privilege, this account should NOT be a domain administrator, or have any elevated privileges in the domain.

Закройте PowerShell. Close PowerShell. Перезапустите консоль PowerShell, только на этот раз щелкните правой кнопкой мыши ярлык Windows PowerShell и выберите пункт Запуск от имени администратора, как показано на рис. 1-5. Relaunch the PowerShell console, except this time right-click on the Windows PowerShell shortcut and select Run as administrator as shown in Figure 1-5.

Если вы выполнили вход в Windows в качестве обычного пользователя, вам будет предложено ввести учетные данные. If you’re logged into Windows as a normal user, you’ll be prompted for credentials. Я буду вводить учетные данные учетной записи пользователя, которая является пользователем домена и локальным администратором, как показано на рис. 1-6. I’ll enter the credentials for my user account who is a domain user and local admin as shown in Figure 1-6.

После повторного запуска PowerShell с правами администратора в строке заголовка должно быть указано «Администратор: Windows PowerShell», как показано на рис. 1-7. Once PowerShell is relaunched as an administrator, the title bar should say «Administrator: Windows PowerShell» as shown in Figure 1-7.

Теперь, когда PowerShell работает с повышенными привилегиями локального администратора, управление доступом пользователей больше не будет проблемой в случае запуска на локальном компьютере команды, для выполнения которой обычно требуется запрос на повышение прав. Now that PowerShell is being run elevated as a local administrator, UAC will no longer be a problem when a command is run on the local computer that would normally require a prompt for elevation. Следует иметь в виду, что любая команда, выполняемая из этого экземпляра консоли PowerShell с повышенными привилегиями, также запускается с повышенными привилегиями. Keep in mind though that any command run from this elevated instance of the PowerShell console, also runs elevated.

Чтобы упростить поиск PowerShell и запускать оболочку от имени администратора, рекомендуется закрепить ее на панели задач и настроить автоматический запуск от имени администратора при каждом запуске. To simplify finding PowerShell and launching it as an administrator, I recommend pinning it to the taskbar and setting it to automatically launch as an admin each time it’s run.

Еще раз выполните поиск PowerShell, только на этот раз щелкните ее правой кнопкой мыши и выберите пункт «Закрепить на панели задач», как показано на рис. 1-8. Search for PowerShell again, except this time right-click on it and select «Pin to taskbar» as shown in Figure 1-8.

Щелкните правой кнопкой мыши ярлык PowerShell, который теперь закреплен на панели задач, и выберите пункт «Свойства», как показано на рис. 1-9. Right-click on the PowerShell shortcut that’s now pinned to the taskbar and select properties as shown in Figure 1-9.

Щелкните «Дополнительно», как показано в первой части рис. 1-10, установите флажок «Запуск от имени администратора», как показано во второй части рис. 1-10, а затем дважды нажмите кнопку OK, чтобы принять изменения и выйти из обоих диалоговых окон. Click on «Advanced» as denoted by #1 in Figure 1-10, then check the «Run as administrator» checkbox as denoted by #2 in Figure 1-10, and then click OK twice to accept the changes and exit out of both dialog boxes.

Вам больше никогда не придется беспокоиться о поиске PowerShell или о том, запущена ли оболочка от имени администратора или нет. You’ll never have to worry about finding PowerShell or whether or not it’s running as an administrator again.

Запуск PowerShell с повышенными привилегиями для предотвращения проблем, связанных с управлением доступом пользователей, влияет только на команды, выполняемые на локальном компьютере. Running PowerShell elevated as an administrator to prevent having problems with UAC only impacts commands that are run against the local computer. Он не влияет на команды, предназначенные для запуска на удаленных компьютерах. It has no effect on commands that target remote computers.

Какую версию PowerShell я использую? What version of PowerShell am I running?

В PowerShell существует ряд автоматических переменных, в которых хранятся сведения о состоянии. There are a number of automatic variables in PowerShell that store state information. Одной из этих переменных является $PSVersionTable , содержащая хэш-таблицу, которую можно использовать для вывода соответствующих сведений о версии PowerShell. One of these variables is $PSVersionTable , which contains a hashtable that can be used to display the relevant PowerShell version information:

Более новые версии Windows PowerShell распространяются в составе Windows Management Framework (WMF). Newer versions of Windows PowerShell are distributed as part of the Windows Management Framework (WMF). Конкретная версия .NET Framework зависит от версии WMF. A specific version of the .NET Framework is required depending on the WMF version. Сведения об обновлении до версии PowerShell 5.1 см. в разделе Обновление существующей версии Windows PowerShell. To upgrade to Windows PowerShell 5.1, see Upgrading existing Windows PowerShell.

Политика выполнения Execution Policy

Вопреки распространенному мнению, политика выполнения в PowerShell не является средством обеспечения безопасности. Contrary to popular belief, the execution policy in PowerShell is not a security boundary. Она предназначена для предотвращения непреднамеренного выполнения сценария пользователем. It’s designed to prevent a user from unknowingly running a script. Определенный пользователь может без труда обойти политику выполнения в PowerShell. A determined user can easily bypass the execution policy in PowerShell. В таблице 1-2 показана политика выполнения по умолчанию для текущих операционных систем Windows. Table 1-2 shows the default execution policy for current Windows operating systems.

Любая команда PowerShell может выполняться в интерактивном режиме, независимо от настройки политики выполнения. Regardless of the execution policy setting, any PowerShell command can be run interactively. Политика выполнения влияет только на команды, выполняемые в сценарии. The execution policy only affects commands running in a script. Командлет Get-ExecutionPolicy используется для определения текущего параметра политики выполнения, а командлет Set-ExecutionPolicy используется для изменения политики выполнения. The Get-ExecutionPolicy cmdlet is used to determine what the current execution policy setting is and the Set-ExecutionPolicy cmdlet is used to change the execution policy. Рекомендуется использовать политику RemoteSigned, которая требует, чтобы предназначенные для выполнения скачиваемые сценарии были подписаны доверенным издателем. My recommendation is to use the RemoteSigned policy, which requires downloaded scripts to be signed by a trusted publisher in order to be run.

Проверка текущей политики выполнения Check the current execution policy:

Если для политики выполнения задано С ограниченным доступом, сценарии PowerShell вообще не запускаются. PowerShell scripts can’t be run at all when the execution policy is set to Restricted. Это параметр по умолчанию для всех клиентских операционных систем Windows. This is the default setting on all Windows client operating systems. Чтобы продемонстрировать проблему, сохраните следующий код как файл .ps1 с именем Stop-TimeService.ps1 . To demonstrate the problem, save the following code as a .ps1 file named Stop-TimeService.ps1 .

Эта команда выполняется в интерактивном режиме без ошибок при условии, что PowerShell запущена с повышенными правами администратора. That command runs interactively without error as long as PowerShell is run elevated as an administrator. Но при сохранении в виде файла сценария и попытке выполнить сценарий выдается ошибка. But as soon as it’s saved as a script file and you try to execute the script, it generates an error:

Обратите внимание, что в сообщении об ошибке, приведенном в предыдущем наборе результатов, указывается точная проблема (в этой системе отключено выполнение сценариев). Notice that the error shown in the previous set of results tells you exactly what the problem is (running scripts is disabled on this system). При выполнении в PowerShell команды, которая создает сообщение об ошибке, обязательно следует прочесть сообщение об ошибке, а не просто перезапустить команду и надеяться на ее успешное завершение. When you run a command in PowerShell that generates an error message, be sure to read the error message instead of just rerunning the command and hoping that it runs successfully.

Измените политику выполнения PowerShell на удаленно подписанную. Change the PowerShell execution policy to remote signed.

Обязательно прочтите предупреждение, которое отображается при изменении политики выполнения. Be sure to read the warning that’s displayed when changing the execution policy. Кроме того, рекомендуется ознакомиться с разделом справки about_Execution_Policies, чтобы знать о влиянии изменения политики выполнения на безопасность. I also recommend taking a look at the about_Execution_Policies help topic to make sure you understand the security implications of changing the execution policy.

Теперь, когда для политики выполнения задано значение Удаленно подписанная, сценарий Stop-TimeService.ps1 будет выполняться без ошибок. Now that the execution policy has been set to RemoteSigned, the Stop-TimeService.ps1 script runs error free.

Прежде чем продолжить, запустите службу времени Windows. В противном случае могут возникнуть непредвиденные проблемы. Be sure to start your Windows Time service before continuing otherwise you may run into unforeseen problems.

Сводка Summary

В этой главе вы узнали, как найти и запустить PowerShell, а также как создать ярлык для запуска PowerShell от имени администратора. In this chapter, you’ve learned how to find and launch PowerShell, and how to create a shortcut that launches PowerShell as an administrator. Вы также ознакомились с политикой выполнения по умолчанию и поняли, как ее изменять. You’ve also learned about the default execution policy and how to change it.

Просмотр Review

1. Как определить версию PowerShell, установленную на компьютере? How do you determine what PowerShell version a computer is running?
2. Почему важно запускать PowerShell с повышенными правами администратора? Why is it important to launch PowerShell elevated as an administrator?
3. Как определить текущую политику выполнения PowerShell? How do you determine the current PowerShell execution policy?
4. Чему препятствует политика выполнения PowerShell по умолчанию на клиентских компьютерах Windows? What does the default PowerShell execution policy on Windows client computers prevent from occurring?
5. Как изменить политику выполнения PowerShell? How do you change the PowerShell execution policy?

Рекомендуем прочесть Recommended Reading

Тем, кто хочет более подробно изучить темы, описанные в этой главе, рекомендуется ознакомиться со следующими разделами справки по PowerShell. For those who want to know more information about the topics covered in this chapter, I recommend reading the following PowerShell help topics.

В следующей главе вы узнаете о возможности обнаружения команд в PowerShell. In the next chapter, you’ll learn about the discoverability of commands in PowerShell. Помимо прочих вопросов в ней будет рассматриваться обновление PowerShell, после которого разделы справки можно будет просматривать непосредственно в PowerShell, а не в Интернете. One of the things that will be covered is how to update PowerShell so those help topics can be viewed right from within PowerShell instead of having to view them on the internet.