{"id":2693,"date":"2013-10-21T00:01:00","date_gmt":"2013-10-21T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2013\/10\/21\/invokerestmethod-for-the-rest-of-us\/"},"modified":"2013-10-21T00:01:00","modified_gmt":"2013-10-21T00:01:00","slug":"invokerestmethod-for-the-rest-of-us","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/invokerestmethod-for-the-rest-of-us\/","title":{"rendered":"InvokeRestMethod for the Rest of Us"},"content":{"rendered":"

Summary<\/strong>: Learn how to use Windows PowerShell to search web pages.\nScripting Guy, Ed Wilson here. Today’s post is written by Doug Finke, a Windows PowerShell MVP, and June Blender, senior programming writer on the Windows Azure Active Directory team.\nTake it away, June…\nI was bending my brain around the cool new Windows Azure Graph REST APIs<\/a>  and Windows Azure Storage Services REST APIs<\/a>, when I noticed that Doug Finke, author of Windows PowerShell for Developers<\/a> was posting about calling Representational State Transfer (REST) APIs in Windows PowerShell.\nTo give you a bit of background, a REST API is an interface based on the HTTP protocol. You use one of four operations—Get<\/strong>, Post<\/strong>, Put<\/strong>, or Delete<\/strong>—with a string parameter in HTTP format. The strings look like URIs, but they don’t refer to a web page. Instead, they provide the data for one of the four operations.\nI didn’t know how to call REST APIs in Windows PowerShell, so I asked Doug for help. Before we started, I asked Doug how to determine which websites have web services with REST interfaces. It turns out that this isn’t a very straightforward task. You have to search online for the name of your favorite website or service and “REST API.” Doug found YouTube and StackOverflow, and he pointed me to the ProgrammableWeb  API search<\/a>.\nDoug suggested that we start with the Invoke-RestMethod<\/a> cmdlet, which was introduced in Windows PowerShell 3.0, and YouTube, which has a well-documented REST API. I started here: YouTube API v2.0 – API Query Parameters<\/a>. This page lists the parameters that you can include in a Get<\/strong> or query operation.\nThe syntax of the query string is:<\/p>\n

https:\/\/gdata.youtube.com\/feeds\/api\/videos?\n…followed by a parameter and parameter value in key=value format.\nFor example, the instructions recommend that you include the v<\/strong> (version) parameter with a value of 2<\/strong> to use the latest version of the REST API:<\/p>\n

https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2\nTo specify the query string (the text you are searching for), use a parameter of q <\/strong>(lower-case) and the search text. This query string searches for PowerShell<\/strong>:<\/p>\n

https:\/\/gdata.youtube.com\/feeds\/api\/videos?q=PowerShell\nTo search for multiple words, concatenate the words with a plus sign (+<\/strong>).<\/p>\n

https:\/\/gdata.youtube.com\/feeds\/api\/videos?q=Windows+PowerShell\nTo use multiple parameters, separate them with an ampersand (&<\/strong>). The following query string specifies v 2<\/strong> and searches for PowerShell<\/strong>:<\/p>\n

https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=Powershell\nNow, to run the query in Windows PowerShell, use the Invoke-RestMethod<\/strong> cmdlet. The following command searches YouTube videos with PowerShell<\/strong> in the title.<\/p>\n

PS C:> Invoke-RestMethod -Uri  “https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=PowerShell”<\/p>\n

 <\/p>\n

etag          : W\/”D0UNQH47eCp7I2A9Wh5TFU4.”<\/p>\n

id            : tag:youtube.com,2008:video:-Ya1dQ1Igkc<\/p>\n

published     : 2012-03-27T19:43:26.000Z<\/p>\n

updated       : 2013-09-30T10:01:31.000Z<\/p>\n

category      : {category, category}<\/p>\n

title         : My Final 1-Day PowerShell v2 Workshop<\/p>\n

content       : content<\/p>\n

link          : {link, link, link, link…}<\/p>\n

author        : author<\/p>\n

accessControl : {yt:accessControl, yt:accessControl, yt:accessControl, yt:accessControl…}<\/p>\n

comments      : comments<\/p>\n

group         : group<\/p>\n

rating        : {gd:rating, yt:rating}<\/p>\n

statistics    : statistics<\/p>\n

 <\/p>\n

etag          : W\/”DU8DRn47eCp7I2A9WhFaGE0.”<\/p>\n

id            : tag:youtube.com,2008:video:XpHgSHQZNpU<\/p>\n

published     : 2011-09-21T15:38:13.000Z<\/p>\n

updated       : 2013-09-21T23:57:57.000Z<\/p>\n

category      : {category, category}<\/p>\n

title         : Hacking Windows Accounts with Powershell<\/p>\n

content       : content<\/p>\n

link          : {link, link, link, link…}<\/p>\n

author        : author<\/p>\n

accessControl : {yt:accessControl, yt:accessControl, yt:accessControl, yt:accessControl…}<\/p>\n

comments      : comments<\/p>\n

hd            :<\/p>\n

group         : group<\/p>\n

rating        : {gd:rating, yt:rating}<\/p>\n

statistics    : statistics<\/p>\n

 . . .\nWow, it works!  I’ll select the title, author, and the URL of the video:<\/p>\n

PS C:ps-test> Invoke-RestMethod -Uri “https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=PowerShell” | Select-Object Title, Author, Link<\/p>\n

 <\/p>\n

title                                            author    link<\/p>\n

—–                                            ——    —-<\/p>\n

My Final 1-Day PowerShell v2 Workshop            author    {link, link, link, link…}<\/p>\n

Hacking Windows Accounts with Powershell         author    {link, link, link, link…}<\/p>\n

What is PowerShell and how can it make IT …    author    {link, link, link, link…}<\/p>\n

Basics of Powershell P1                          author    {link, link, link, link…}<\/p>\n

…\nHmm. That doesn’t quite work. The author property is in author.name and the link is in content.src. You can use a calculated property or a PSCustomObject to fix this. Let’s use a PSCustomObject<\/a>.<\/p>\n

PS C:> Invoke-RestMethod -Uri “https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=PowerShell” | foreach {[PSCustomObject]@{Title=$_.Title; Author=$_.Author.name; Link=$_.content.src}} | Format-List<\/p>\n

 <\/p>\n

Title  : My Final 1-Day PowerShell v2 Workshop<\/p>\n

Author : Don Jones<\/p>\n

Link   : https:\/\/www.youtube.com\/v\/-Ya1dQ1Igkc?version=3&f=videos&app=youtube_gdata<\/p>\n

 <\/p>\n

Title  : Hacking Windows Accounts with Powershell<\/p>\n

Author : David Hoelzer<\/p>\n

Link   : https:\/\/www.youtube.com\/v\/XpHgSHQZNpU?version=3&f=videos&app=youtube_gdata<\/p>\n

…\nThat’s much better! There’s lots of other useful information, including the publication date and last updated date, comments, statistics, and ratings.\nBut before I turn you over to Doug to hear why this works, let me share one more tidbit. One of the parameters in the YouTube REST API is Max-Results<\/strong>. Its default value is 25, and its maximum value is 50.\nIt doesn’t seem to work in Windows PowerShell 3.0. By default, it returns the first 13 hits. When we specified values of 5, 10, 30, and 50, we got only half of what we requested: 3, 5, 15, and 25.<\/p>\n

PS C:> (Invoke-RestMethod -Uri “https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=PowerShell”).count<\/p>\n

13<\/p>\n

 <\/p>\n

PS C:> 5,10,30,50 | % {<\/p>\n

    $url=https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=Powershell&max-results=$_;<\/p>\n

    (Invoke-RestMethod $url).count<\/p>\n

}<\/p>\n

3<\/p>\n

5<\/p>\n

15<\/p>\n

25\nBut when we tested it in Windows PowerShell 4.0, it worked perfectly.<\/p>\n

PS C:> (Invoke-RestMethod -Uri “https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=PowerShell”).count<\/p>\n

25<\/p>\n

 <\/p>\n

PS C:> 5,10,30,50 | % {<\/p>\n

    $url=https:\/\/gdata.youtube.com\/feeds\/api\/videos?v=2&q=Powershell&max-results=$_;<\/p>\n

    (Invoke-RestMethod $url).count<\/p>\n

}<\/p>\n

5<\/p>\n

10<\/p>\n

30<\/p>\n

50\nWe checked with Windows PowerShell developer, Lee Holmes; and indeed, in Windows PowerShell 4.0, the team fixed a bug that returned only half of the results of Invoke-RestMethod<\/strong> calls.\nSo, let me turn you over to Doug so you can learn about why all of this works…\nThanks, June. That was a great write-up about how Windows PowerShell integrates with REST APIs.\nREST is the predominant Web API. It’s a way to serve standard programmatic access to data over HTTP. So, as June shows, you can get to a wealth of YouTube data by using a Window PowerShell one-liner.\nThe cool part is that all REST APIs work this way. So, when you learn the fundamentals, you can identify REST sources and apply these techniques again and again.<\/p>\n

Invoke-RestMethod<\/h2>\n

Invoke-RestMethod<\/strong> is great because the Windows PowerShell team has written and tested a ton of script, and I can get super productive with two lines:<\/p>\n

PS C:>$url = “https:\/\/gdata.youtube.com\/feeds\/api\/videos?q=PowerShell”<\/p>\n

PS C:> (Invoke-RestMethod $url).title.’#text’<\/p>\n

 <\/p>\n

My Final 1-Day PowerShell v2 Workshop<\/p>\n

Windows PowerShell 2.0 for Beginners Training & Overview – EPC Group<\/p>\n

Hacking Windows Accounts with Powershell<\/p>\n

Introduction to Windows PowerShell Part 1<\/p>\n

What is PowerShell and how can it make IT more efficient? Jason Helmick – Interface<\/p>\n

Windows PowerShell Remoting: Definitely NOT Just for Servers<\/p>\n

Basics of Powershell P1<\/p>\n

O’Reilly Webcast: Getting Started with Windows PowerShell 3.0<\/p>\n

Advanced Automation Using Windows PowerShell 3.0<\/p>\n

TechEd 2013: Windows PowerShell Unplugged – Jeffrey Snover<\/p>\n

My PowerShell Scripts – Systems Administration<\/p>\n

[Powershell] Einführung Teil 1<\/p>\n

MCITP 70-640: PowerShell<\/p>\n

German PowerShell Basis Video Tutorial Teil 1 von 21 Was ist PowerShell, Warum PowerShell<\/p>\n

Bootable USB Drive Using Powershell and Windows 8<\/p>\n

Инструменты Windows PowerShell 2.0. Часть 1<\/p>\n

Bruce Payette – PowerShell Workflows<\/p>\n

Powershell. Curso Hispano.<\/p>\n

Exploring PowerShell for Beginners Dec 9th<\/p>\n

PowerShell: Introduction and Scripting Tutorial<\/p>\n

No Tools No Problem Building a PowerShell Botnet Christopher @obscuresec Campbell<\/p>\n

Creating HTML Reports with PowerShell<\/p>\n

PowerShell Scripting Basics<\/p>\n

PowerShell for common Office 365 Operations<\/p>\n

Windows Powershell – What are The Top 10 Cmdlets to Start Using Immediately\nTake note of how the ­title information is retrieved:<\/p>\n

 (Invoke-RestMethod $url).title.’#text’\nThe title data is stored in the #text<\/strong> <\/em>property, but if you don’t enclose “#text”<\/strong> in quotation marks, Windows PowerShell interprets it as a comment because it begins with a # <\/em><\/strong>sign, and you will receive an error message.\nBefore Windows PowerShell delivered Invoke-RestMethod<\/strong>, we could reach into the .NET Framework and use the System.Net.WebClient<\/a> class to grab this data ourselves:<\/p>\n

PS C:>$wc = New-Object System.Net.WebClient<\/p>\n

PS C:>$url = “https:\/\/gdata.youtube.com\/feeds\/api\/videos?q=PowerShell”<\/p>\n

PS C:>$youtubedata = [xml]$wc.DownloadString($url)<\/p>\n

PS C:>$youtubedata.feed.entry.title.’#text’\nInvoke-RestMethod<\/strong> does a lot for us. It connects and downloads the data from the target URL, converts the returned string into XML, and extracts the feed.entry<\/strong> information so we can use less .NET notation to get at what we want faster. A feed<\/a> is a data format for providing frequently updated content. Invoke-RestMethod<\/strong> leverages this standard to make our lives easier.\nBut wait! There’s more…<\/p>\n

Earthquake data and JSON<\/h2>\n

Invoke-RestMethod<\/strong> also automatically detects the type of data the URL returns. While REST is the predominate way to interact with data on the web, JavaScript Object Notation<\/a> (JSON), a text-based standard for data interchange, is often used too.\nGreat news! The designers of Invoke-RestMethod<\/strong> also made it easy to interact with JSON REST feeds. Here’s an Invoke-RestMethod<\/strong> command that gets earthquake data from Seismi.org. It returns JSON, but you don’t need to know that. Windows PowerShell returns custom objects (PSCustomObject<\/a>) that you can use in your commands.<\/p>\n

PS C:>(Invoke-RestMethod -URI “http:\/\/www.seismi.org\/api\/eqs”).earthquakes | Select-Object -First 10 | Format-Table –AutoSize<\/p>\n

 <\/p>\n

src eqid     timedate            lat      lon       magnitude depth  region                                              <\/p>\n

— —-     ——–            —      —       ——— —–  ——                                               <\/p>\n

us  c000is61 2013-07-29 22:22:48 7.6413   93.6871   4.6       40.90  Nicobar Islands, India region                       <\/p>\n

us  c000is4s 2013-07-29 21:52:12 -57.7816 -25.3260  5.2       53.50  South Sandwich Islands region                        <\/p>\n

us  c000is3k 2013-07-29 21:33:34 36.6696  71.0615   4.7       234.10 Hindu Kush region, Afghanistan                      <\/p>\n

us  c000irvf 2013-07-29 18:27:41 -37.2993 177.2515  4.9       160.50 off the east coast of the North Island of New Zealand<\/p>\n

us  c000irpf 2013-07-29 14:53:32 24.5038  62.5255   4.5       24.30  off the coast of Pakistan                           <\/p>\n

us  c000irl3 2013-07-29 10:23:35 45.9104  143.0497  4.4       337.70 Hokkaido, Japan region                              <\/p>\n

us  c000irjj 2013-07-29 08:21:31 -6.8134  130.2114  4.6       87.80  Banda Sea                                           <\/p>\n

us  c000irjf 2013-07-29 08:12:27 -16.9852 -177.0945 5.1       10.00  Fiji region                                         <\/p>\n

us  c000irj9 2013-07-29 08:08:00 36.5108  70.5896   5.0       193.10 Hindu Kush region, Afghanistan                      <\/p>\n

us  c000irhe 2013-07-29 05:49:35 -4.6368  -104.9759 4.7       10.00  central East Pacific Rise                            \nYou can use the WebClient<\/strong> class to build a command like this on your own. Prior to Windows PowerShell 3.0, you’d need to use a third-party .NET JSON parser or build your own. Windows PowerShell 3.0 introduced the ConvertFrom-Json<\/a> cmdlet:<\/p>\n

PS C:>$wc = New-Object System.Net.WebClient<\/p>\n

PS C:>$data = $wc.DownloadString(“http:\/\/www.seismi.org\/api\/eqs”) | ConvertFrom-Json<\/p>\n

PS C:>$data.earthquakes | select -First 10 | Format-Table -AutoSize\nThe results are much noisier than the out-of-the-box experience of Invoke-RestMethod<\/strong>. Plus, Invoke-RestMethod <\/strong>automatically detects whether XML or JSON is being returned, and it does the right thing—it returns Windows PowerShell objects for you to easily work on.<\/p>\n

Invoke-RestMethod under the covers<\/h2>\n

Invoke-RestMethod<\/strong> is one of the Windows PowerShell 3.0 core cmdlets. It is written in C# and delivered in the Microsoft.PowerShell.Commands.Utility.dll. To examine it, I used a free tool from JetBrains, called DotPeek<\/a>. This tool can look into the compiled DLL and decompile it to source code so you can browse it.\nAfter reading the Invoke-RestMethod<\/strong> code, I asked the Windows PowerShell team to confirm my assumptions. Lee Holmes, author of the great book, Windows PowerShell Cookbook, 3rd<\/sup> Edition<\/a>, replied, “If it looks like an RSS or ATOM feed, we process and return the elements in the feed. If the response says it returns some form of JSON (there are many), we will first try to convert it to JSON. If that fails, we will convert it to XML. If that fails, we return it as text.”\nHere is a simplified Windows PowerShell version I came up with that I sent along with the question: <\/p>\n

$url = “http:\/\/www.seismi.org\/api\/eqs”<\/p>\n

 <\/p>\n

$request = [System.Net.WebRequest]::Create($url)<\/p>\n

$request.Method=”Get”<\/p>\n

$response = $request.GetResponse()<\/p>\n

$requestStream = $response.GetResponseStream()<\/p>\n

$readStream = New-Object System.IO.StreamReader $requestStream<\/p>\n

 <\/p>\n

$data=$readStream.ReadToEnd()<\/p>\n

 <\/p>\n

if($response.ContentType -match “application\/xml”) {<\/p>\n

    $results = [xml]$data<\/p>\n

} elseif($response.ContentType -match “application\/json”) {<\/p>\n

    $results = $data | ConvertFrom-Json<\/p>\n

} else {<\/p>\n

    try {<\/p>\n

        $results = [xml]$data<\/p>\n

    } catch {<\/p>\n

        $results = $data | ConvertFrom-Json<\/p>\n

    }<\/p>\n

}<\/p>\n

 <\/p>\n

$results \nThese 23 lines of code give the same results for the earthquake data as the one-line that used Invoke-RestMethod<\/strong>. Thank you, Windows PowerShell team!\nThat’s a very simple overview of how YouTube and Seismi.org serve this information. The better news is that this is a web standard and many sources of data are available to you this way. Even better, Windows PowerShell makes working with this information a breeze.\n~Doug\nThanks, June and Doug.\nI invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.\nEd Wilson<\/strong>, Microsoft Scripting Guy<\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Learn how to use Windows PowerShell to search web pages. Scripting Guy, Ed Wilson here. Today’s post is written by Doug Finke, a Windows PowerShell MVP, and June Blender, senior programming writer on the Windows Azure Active Directory team. Take it away, June… I was bending my brain around the cool new Windows Azure Graph […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[78,56,370,3,4,45],"class_list":["post-2693","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-doug-finke","tag-guest-blogger","tag-june-blender","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Learn how to use Windows PowerShell to search web pages. Scripting Guy, Ed Wilson here. Today’s post is written by Doug Finke, a Windows PowerShell MVP, and June Blender, senior programming writer on the Windows Azure Active Directory team. Take it away, June… I was bending my brain around the cool new Windows Azure Graph […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/2693","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=2693"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/2693\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=2693"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=2693"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=2693"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}