Advanced Hunting API: Add page for Flow instructions and page for PowerShell instructions

windows/security/threat-protection/windows-defender-atp/TOC.md

@@ -100,6 +100,9 @@
 ### [**Beta!** Use Windows Defender ATP APIs](exposed-apis-windows-defender-advanced-threat-protection-new.md)
 #### [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection-new.md)
 ##### [Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection.md)
+#### [Examples how to use APIs]
+##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md)
+##### [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md)
 
 
 ### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md

@@ -0,0 +1,84 @@
+---
+title: Advanced Hunting API
+description: Use this API to run advanced queries
+keywords: apis, supported apis, advanced hunting, query
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+ms.date: 12/08/2017
+---
+
+# Schedule Advanced Hunting using Microsoft Flow 
+
+**Applies to:**
+
+- Windows Defender Advanced Threat Protection (Windows Defender ATP)
+
+Schedule advanced query.
+
+## Use case
+
+You need to schedule an advanced query and use the result for follow up actions and processing.
+
+You can use [Microsoft Flow](https://flow.microsoft.com/) (or Logic Apps) for it!
+
+## Define a flow to run query and parse results
+
+You will find below a very basic flow example:
+
+1. Define the trigger – Recurrence by time
+
+2. Add an action – Select HTTP
+
+	![Image of MsFlow choose an action](images/ms-flow-choose-action.png)
+
+	- Set method to be POST
+	- Uri is https://api.securitycenter.windows.com/advancedqueries/query or one of the region specific locations
+		- US: https://api-us.securitycenter.windows.com/advancedqueries/query
+		- Europe: https://api-eu.securitycenter.windows.com/advancedqueries/query
+		- United Kingdom: https://api-uk.securitycenter.windows.com/advancedqueries/query
+	- Add the Header: Content-Type              application/json
+	- In the body write your query surrounded by single quotation mark (')
+	- In the Advanced options select Authentication to be Active Directory OAuth
+	- Set the Tenant with proper AAD Tenant Id
+	- Audience is https://securitycenter.onmicrosoft.com/windowsatpservice
+	- Client ID is your application ID
+	- Credential Type should be Secret
+	- Secret is the application secret generated in the Azure Active directory.
+
+	![Image of MsFlow define action](images/ms-flow-define-action.png)
+
+3. You can use the "Parse JSON" action to get the schema of data – just "use sample payload to generate schema" and copy an output from of the expected result.
+
+	![Image of MsFlow parse json](images/ms-flow-parse-json.png)
+
+## Expand the flow to use the query results
+
+The below section shows how to use the parsed results to insert them in SQL database.
+
+This is an example only, you could perform on your results any other action supported by Microsoft Flow.
+
+	- Add an 'Apply to each' action
+	- Select the Results json (which was an output of the last parse action)
+	- Add an 'Insert row' action – you will need to supply the connection details
+	- Select the table you want to update and define the mapping between the WD-ATP output to the SQL. Note it is possible to manipulate the data inside the flow. In the example I changed the type of the EventTime.
+
+	![Image of select from DB](images/ms-flow-insert-db.png)
+
+The output in the SQL DB is getting updates and can be used for correlation with other data sources. You can now read from your table:
+
+	![Image of select from DB](images/ms-flow-read-db.png)
+
+You can find below the full definition
+
+	![Image of select from DB](images/ms-flow-e2e.png)
+
+## Related topic
+- [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md)
+- [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md)
+- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md

@@ -0,0 +1,76 @@
+---
+title: Advanced Hunting API
+description: Use this API to run advanced queries
+keywords: apis, supported apis, advanced hunting, query
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+ms.date: 12/08/2017
+---
+
+# Advanced Hunting using PowerShell
+
+Run advanced queries using PowerShell. Please read about [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md) before.
+
+## Preparation Instructions
+
+In this section you will find a PowerShell module that retrieves a token and uses it to run a query. You can download the module and use it to run your own query.
+
+- ​​Download and unzip 'AdvancedHunting' PowerShell module.
+- Open a PowerShell window.
+- If your policy does not allow you to run the PowerShell commands, you can run the below command:
+```
+Set-ExecutionPolicy -ExecutionPolicy Bypass
+```
+>Please see PowerShell documentation for full understanding
+
+- Run
+```
+Import-Module <ModuleFolder>\AdvancedHunting.psd1​
+```
+where <ModuleFolder> is the folder in which you extracted the zip.  e.g., Import-Module 'D:\Dev\AAD Auth\AdvancedHunting.psd1'
+
+## Get token
+- Run
+```
+$aadToken = Get-WdatpAppToken -Tid <tenantID> -AppId <applicationID> -AppSecret <applicationSecret>
+```
+where
+- <tenantID>: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant)
+- <applicationID>: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP)
+- <applicationSecret>: Secret of your AAD app
+
+## Run query
+
+Run the below
+
+```
+$response = Invoke-Query -AadToken $aadToken -Query "RegistryEvents | limit 10"​
+$response.results
+$response.schema
+$response.results | ConvertTo-Csv -NoTypeInformation | Set-Content file1.csv
+$response.results | ConvertTo-Json | Set-Content "file1.json"
+```
+
+- Line 2 and 3 will show you the results or the schema in the PowerShell window
+- Line 4 outputs the results of the query in CSV format in file file1.csv
+- Line 5 outputs the results of the query in JSON format in file file1.json​
+
+If you want to run complex queries (or multilines queries), save your query in a file and run the below commands:
+>Replace C:\myQuery.txt with the path to your file.
+
+```
+​​​​$myQuery = [IO.File]::ReadAllText("C:\myQuery.txt");
+$queryResults = Invoke-Query -AadToken $aadToken -Query $myQuery​​​
+```
+
+
+## Related topic
+- [Advanced Hunting API](run-advanced-query-windows-defender-advanced-threat-protection.md)
+- [Schedule Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md)
+- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)

windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection.md

@@ -22,8 +22,14 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
+This API allows you to run programatically queries that you are used to run from [Windows Defender ATP Portal](https://securitycenter.windows.com/hunting)
 
-Run advanced query.
+
+## Limitations
+This API is a beta version only and is currently restricted
+1. ​You can only run a query on data from the last 30 days
+2. The results will include a maximum of 10,000 rows
+3. The nu​mber of executions is limited​ (up to 15 minutes every hour and 4 hours a day)
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -61,6 +67,12 @@ Request
 
 Here is an example of the request.
 
+>[!NOTE]
+>For better performance, you can use server closer to your geo location:
+> - api-us.securitycenter.windows.com
+> - api-eu.securitycenter.windows.com
+> - api-uk.securitycenter.windows.com
+
 ```
 POST https://api.securitycenter.windows.com/advancedqueries/query
 Content-type: application/json
@@ -110,3 +122,17 @@ Content-Type: application/json​
 
 
 ```
+
+## T​roubl​eshooting:
+
+	- (403) Forbidden.
+	
+	If you get this error when calling WDATP API, your token probably does not include the necessary permission.
+	Please refer to section "Verify you can access WDATP app using your app" in Create an AAD app.
+	If the 'roles' section in the token does not include the necessary permission, either you did not add the necessary permission to your app (refer to step 6 in Create an AAD app) or you did not authorized your app in the tenant (refer to "Application consent" in Create an AAD app​)
+
+
+## Related topic
+- [Advanced Hunting using PowerShell](run-advanced-query-windows-defender-advanced-threat-protection-sample-powershell.md)
+- [Schedule Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection-sample-ms-flow.md)
+- [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md)