Merge pull request #967 from MicrosoftDocs/atp-api-update+examples

ATP API update + examples

.openpublishing.redirection.json

@@ -14862,19 +14862,14 @@
 "redirect_document_id": true
 },
 {
-"source_path": "windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md",
+  "source_path": "windows/security/threat-protection/windows-defender-atp/api-microsoft-flow.md",
-"redirect_url": "/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-ms-flow",
+  "redirect_url": "/windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow",
-"redirect_document_id": true
+  "redirect_document_id": true
 },
 {
-"source_path": "windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-app-token.md",
+  "source_path": "windows/security/threat-protection/windows-defender-atp/api-power-bi.md",
-"redirect_url": "/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-power-bi-app-token",
+  "redirect_url": "/windows/security/threat-protection/microsoft-defender-atp/api-power-bi",
-"redirect_document_id": true
+  "redirect_document_id": true
-},
-{
-"source_path": "windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-user-token.md",
-"redirect_url": "/windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-power-bi-user-token",
-"redirect_document_id": true
 },
 {
 "source_path": "windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-powershell.md",

windows/security/threat-protection/TOC.md

@@ -418,15 +418,10 @@
 ####### [Get user related machines](microsoft-defender-atp/get-user-related-machines.md)
 
 ##### [How to use APIs - Samples]()
-###### [Advanced Hunting API]()
+###### [Microsoft Flow](microsoft-defender-atp/api-microsoft-flow.md)
-####### [Schedule advanced Hunting using Microsoft Flow](microsoft-defender-atp/run-advanced-query-sample-ms-flow.md)
+###### [Power BI](microsoft-defender-atp/api-power-bi.md)
-####### [Advanced Hunting using PowerShell](microsoft-defender-atp/run-advanced-query-sample-powershell.md)
+###### [Advanced Hunting using Python](microsoft-defender-atp/run-advanced-query-sample-python.md)
-####### [Advanced Hunting using Python](microsoft-defender-atp/run-advanced-query-sample-python.md)
+###### [Advanced Hunting using PowerShell](microsoft-defender-atp/run-advanced-query-sample-powershell.md)
-####### [Create custom Power BI reports](microsoft-defender-atp/run-advanced-query-sample-power-bi-app-token.md)
-
-###### [Multiple APIs]()
-####### [PowerShell](microsoft-defender-atp/exposed-apis-full-sample-powershell.md)
-
 ###### [Using OData Queries](microsoft-defender-atp/exposed-apis-odata-samples.md)
 
 #### [Windows updates (KB) info]()

windows/security/threat-protection/microsoft-defender-atp/api-microsoft-flow.md

@@ -0,0 +1,81 @@
+---
+title: Microsoft Defender ATP Flow connector
+ms.reviewer: 
+description: Microsoft Defender ATP Flow connector
+keywords: flow, supported apis, api, Microsoft flow, query, automation
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+manager: dansimp
+audience: ITPro
+ms.collection: M365-security-compliance 
+ms.topic: article
+---
+
+# Microsoft Defender ATP Flow connector
+
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+
+Automating security procedures is a standard requirement for every modern Security Operations Center. The lack of professional Cyber defenders, forces SOC to work in the most efficient way and automation is a must. MS flow supports different connectors that were built exactly for that. You can build an end-to-end procedure automation within few minutes.
+
+Microsoft Defender API has an official Flow Connector with a lot of capabilities: 
+
+![Image of edit credentials](images/api-flow-0.png)
+
+## Usage example
+
+The following example demonstrates how you can create a Flow that will be triggered any time a new Alert occurs on your tenant.
+
+- Login to [Microsoft Flow](https://flow.microsoft.com)
+
+- Go to: My flows > New > Automated 
+
+![Image of edit credentials](images/api-flow-1.png)
+
+- Choose a name for your Flow, Search for **Microsoft Defender ATP Triggers** as the trigger and choose the new Alerts trigger.
+
+![Image of edit credentials](images/api-flow-2.png)
+
+- Now you have a Flow that is triggered every time a new Alert occurs. 
+
+![Image of edit credentials](images/api-flow-3.png)
+
+All you need to do now, is to choose your next steps.
+Lets, for example, Isolate the machine if the Severity of the Alert is **High** and mail about it.
+The Alert trigger gives us only the Alert ID and the Machine ID. We can use the Connector to expand these entities.
+
+### Get the Alert entity using the connector 
+
+- Choose Microsoft Defender ATP for new step. 
+
+- Choose Alerts - Get single alert API.
+
+- Set the Alert Id from the last step as Input.
+
+![Image of edit credentials](images/api-flow-4.png)
+
+### Isolate the machine if the Alert's severity is High
+
+- Add **Condition** as a new step .
+
+- Check if Alert severity equals to **High**.
+
+- If yes, add Microsoft Defender ATP - Isolate machine action with the Machine Id and a comment.
+
+![Image of edit credentials](images/api-flow-5.png)
+
+Now you can add a new step for mailing about the Alert and the Isolation.
+There are multiple Email connectors that are very easy to use, e.g. Outlook, GMail, etc..
+Save your flow and that's all.
+
+- You can also create **scheduled** flow that will run Advanced Hunting queries and much more! 
+
+## Related topic
+- [Microsoft Defender ATP APIs](apis-intro.md)

windows/security/threat-protection/microsoft-defender-atp/api-power-bi.md

@@ -1,8 +1,8 @@
 ---
-title: Advanced Hunting API
+title: Microsoft Defender ATP APIs connection to Power BI
 ms.reviewer: 
-description: Use this API to run advanced queries
+description: Create custom reports using Power BI
-keywords: apis, supported apis, advanced hunting, query
+keywords: apis, supported apis, Power BI, reports
 search.product: eADQiWindows 10XVcnh
 ms.prod: w10
 ms.mktglfcycl: deploy
@@ -17,24 +17,17 @@ ms.collection: M365-security-compliance
 ms.topic: article
 ---
 
-# Create custom reports using Power BI (user authentication)
+# Create custom reports using Power BI
 
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
 
-[!include[Prerelease information](prerelease.md)]
+In this section you will learn create a Power BI report on top of Microsoft Defender ATP APIs.
 
-Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
+The first example demonstrates how to connect Power BI to Advanced Hunting API and the second example demonstrates a connection to our OData APIs (e.g. Machine Actions, Alerts, etc..)
 
-In this section we share Power BI query sample to run a query using **user token**.
+## Connect Power BI to Advanced Hunting API
-
-If you want to use **application token** instead please refer to [this](run-advanced-query-sample-power-bi-app-token.md) tutorial.
-
-## Before you begin
-You first need to [create an app](exposed-apis-create-app-nativeapp.md).
-
-## Run a query
 
 - Open Microsoft Power BI
 
@@ -46,18 +39,15 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
 
     ![Image of open advanced editor](images/power-bi-open-advanced-editor.png)
 
-- Copy the below and paste it in the editor, after you update the values of Query
+- Copy the below and paste it in the editor:
 
-	```
+```
 	let 
+		AdvancedHuntingQuery = "MiscEvents | where ActionType contains 'Anti'",
 
-		Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId",
+		HuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries",
 
-		FormattedQuery= Uri.EscapeDataString(Query),
+		Response = Json.Document(Web.Contents(HuntingUrl, [Query=[key=AdvancedHuntingQuery]])),
-
-		AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries?key=" & FormattedQuery,
-
-		Response = Json.Document(Web.Contents(AdvancedHuntingUrl)),
 
 		TypeMap = #table(
 			{ "Type", "PowerBiType" },
@@ -88,12 +78,10 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
 
 	in Table
 
-	```
+```
 
 - Click **Done**
 
-    ![Image of create advanced query](images/power-bi-create-advanced-query.png)
-
 - Click **Edit Credentials**
 
     ![Image of edit credentials](images/power-bi-edit-credentials.png)
@@ -108,13 +96,32 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
 
     ![Image of set credentials](images/power-bi-set-credentials-organizational-cont.png)
 
-- View the results of your query
+- Now the results of your query will appear as table and you can start build visualizations on top of it!
 
-    ![Image of query results](images/power-bi-query-results.png)
+- You can duplicate this table, rename it and edit the Advanced Hunting query inside to get any data you would like.
+
+## Connect Power BI to OData APIs
+
+- The only difference from the above example is the query inside the editor. 
+
+- Copy the below and paste it in the editor to pull all **Machine Actions** from your organization:
+
+```
+	let
+
+		Query = "MachineActions",
+
+		Source = OData.Feed("https://api.securitycenter.windows.com/api/" & Query, null, [Implementation="2.0", MoreColumns=true])
+	in
+		Source
+
+```
+
+- You can do the same for **Alerts** and **Machines**.
+
+- You also can use OData queries for queries filters, see [Using OData Queries](exposed-apis-odata-samples.md)
 
 ## Related topic
-- [Create custom Power BI reports with app authentication](run-advanced-query-sample-power-bi-app-token.md)
 - [Microsoft Defender ATP APIs](apis-intro.md)
 - [Advanced Hunting API](run-advanced-query-api.md)
-- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
+- [Using OData Queries](exposed-apis-odata-samples.md)
-- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)

windows/security/threat-protection/microsoft-defender-atp/exposed-apis-full-sample-powershell.md

@@ -117,4 +117,3 @@ $response
 - [Microsoft Defender ATP APIs](apis-intro.md)
 - [Advanced Hunting API](run-advanced-query-api.md)
 - [Advanced Hunting using Python](run-advanced-query-sample-python.md)
-- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)

windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt

@@ -413,15 +413,10 @@
 ####### [Get user related machines](get-user-related-machines.md)
 
 ##### [How to use APIs - Samples]()
-###### [Advanced Hunting API]()
+###### [Microsoft Flow](api-microsoft-flow.md)
-####### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md)
+###### [Power BI](api-power-bi.md)
-####### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
+###### [Advanced Hunting using Python](run-advanced-query-sample-python.md)
-####### [Advanced Hunting using Python](run-advanced-query-sample-python.md)
+###### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
-####### [Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md)
-
-###### [Multiple APIs]()
-####### [PowerShell](exposed-apis-full-sample-powershell.md)
-
 ###### [Using OData Queries](exposed-apis-odata-samples.md)
 
 #### [API for custom alerts]()

windows/security/threat-protection/microsoft-defender-atp/powerbi-reports.md

@@ -202,7 +202,7 @@ In general, if you know of a specific threat name, CVE, or KB, you can identify
 
 
 ## Related topic
-- [**Beta** Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md)
+- [Create custom Power BI reports](api-power-bi.md)
 
 
 

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

@@ -147,4 +147,3 @@ If the 'roles' section in the token does not include the necessary permission:
 - [Microsoft Defender ATP APIs](apis-intro.md)
 - [Advanced Hunting from Portal](advanced-hunting.md)
 - [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
-- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)

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

@@ -1,92 +0,0 @@
----
-title: Advanced Hunting API
-ms.reviewer: 
-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
-manager: dansimp
-audience: ITPro
-ms.collection: M365-security-compliance 
-ms.topic: article
----
-
-# Schedule Advanced Hunting using Microsoft Flow 
-**Applies to:**
-- Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)
-
-[!include[Prerelease information](prerelease.md)]
-
-Schedule advanced query.
-
-## Before you begin
-You first need to [create an app](apis-intro.md).
-
-## Use case
-
-A common scenario is scheduling an advanced query and using the results for follow up actions and processing.
-In this section we share sample for this purpose using [Microsoft Flow](https://flow.microsoft.com/) (or [Logic Apps](https://azure.microsoft.com/services/logic-apps/)).
-
-## Define a flow to run query and parse results
-
-Use the following basic flow as an 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/api/advancedqueries/run or one of the region specific locations
-       - US: https://api-us.securitycenter.windows.com/api/advancedqueries/run
-       - Europe: https://api-eu.securitycenter.windows.com/api/advancedqueries/run
-       - United Kingdom: https://api-uk.securitycenter.windows.com/api/advancedqueries/run
-   - 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://api.securitycenter.windows.com
-   - 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 following section shows how to use the parsed results to insert them in SQL database.
-
-This is an example only, you can  use other actions 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 insert into 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)
-
-## Full flow definition
-
-You can find below the full definition
-
-![Image of E2E flow](images/ms-flow-e2e.png)
-
-## Related topic
-- [Microsoft Defender ATP APIs](apis-intro.md)
-- [Advanced Hunting API](run-advanced-query-api.md)
-- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)

windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-sample-power-bi-app-token.md

@@ -1,138 +0,0 @@
----
-title: Advanced Hunting API
-ms.reviewer: 
-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
-manager: dansimp
-audience: ITPro
-ms.collection: M365-security-compliance 
-ms.topic: article
----
-
-# Create custom reports using Power BI (app authentication)
-
-Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
-
-In this section we share Power BI query sample to run a query using **application token**.
-
-If you want to use **user token** instead please refer to [this](run-advanced-query-sample-power-bi-user-token.md) tutorial.
-
->**Prerequisite**: You first need to [create an app](exposed-apis-create-app-webapp.md).
-
-## Run a query
-
-- Open Microsoft Power BI
-
-- Click **Get Data** > **Blank Query**
-
-    ![Image of create blank query](images/power-bi-create-blank-query.png)
-
-- Click **Advanced Editor**
-
-    ![Image of open advanced editor](images/power-bi-open-advanced-editor.png)
-
-- Copy the below and paste it in the editor, after you update the values of TenantId, AppId, AppSecret, Query
-
-	```
-	let 
-
-		TenantId = "00000000-0000-0000-0000-000000000000", // Paste your own tenant ID here
-		AppId = "11111111-1111-1111-1111-111111111111", // Paste your own app ID here
-		AppSecret = "22222222-2222-2222-2222-222222222222", // Paste your own app secret here
-		Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId", // Paste your own query here
-    
-		ResourceAppIdUrl = "https://api.securitycenter.windows.com",
-		OAuthUrl = Text.Combine({"https://login.windows.net/", TenantId, "/oauth2/token"}, ""),
-
-		Resource = Text.Combine({"resource", Uri.EscapeDataString(ResourceAppIdUrl)}, "="),
-		ClientId = Text.Combine({"client_id", AppId}, "="),
-		ClientSecret = Text.Combine({"client_secret", Uri.EscapeDataString(AppSecret)}, "="),
-		GrantType = Text.Combine({"grant_type", "client_credentials"}, "="),
-	
-		Body = Text.Combine({Resource, ClientId, ClientSecret, GrantType}, "&"),
-
-		AuthResponse= Json.Document(Web.Contents(OAuthUrl, [Content=Text.ToBinary(Body)])),
-		AccessToken= AuthResponse[access_token],
-		Bearer = Text.Combine({"Bearer", AccessToken}, " "),
-    
-		AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries/run",
-    
-		Response = Json.Document(Web.Contents(
-			AdvancedHuntingUrl, 
-			[
-				Headers = [#"Content-Type"="application/json", #"Accept"="application/json", #"Authorization"=Bearer],
-				Content=Json.FromValue([#"Query"=Query])
-			]
-		)),
-
-		TypeMap = #table(
-			{ "Type", "PowerBiType" },
-			{
-				{ "Double",   Double.Type },
-				{ "Int64",    Int64.Type },
-				{ "Int32",    Int32.Type },
-				{ "Int16",    Int16.Type },
-				{ "UInt64",   Number.Type },
-				{ "UInt32",   Number.Type },
-				{ "UInt16",   Number.Type },
-				{ "Byte",     Byte.Type },
-				{ "Single",   Single.Type },
-				{ "Decimal",  Decimal.Type },
-				{ "TimeSpan", Duration.Type },
-				{ "DateTime", DateTimeZone.Type },
-				{ "String",   Text.Type },
-				{ "Boolean",  Logical.Type },
-				{ "SByte",    Logical.Type },
-				{ "Guid",     Text.Type }
-			}),
-
-		Schema = Table.FromRecords(Response[Schema]),
-		TypedSchema = Table.Join(Table.SelectColumns(Schema, {"Name", "Type"}), {"Type"}, TypeMap , {"Type"}),
-		Results = Response[Results],
-		Rows = Table.FromRecords(Results, Schema[Name]),
-		Table = Table.TransformColumnTypes(Rows, Table.ToList(TypedSchema, (c) => {c{0}, c{2}}))
-        
-	in Table
-
-	```
-
-- Click **Done**
-
-    ![Image of create advanced query](images/power-bi-create-advanced-query.png)
-
-- Click **Edit Credentials**
-
-    ![Image of edit credentials](images/power-bi-edit-credentials.png)
-
-- Select **Anonymous** and click **Connect**
-
-    ![Image of set credentials](images/power-bi-set-credentials-anonymous.png)
-
-- Repeat the previous step for the second URL
-
-- Click **Continue**
-
-    ![Image of edit data privacy](images/power-bi-edit-data-privacy.png)
-
-- Select the privacy level you want and click **Save**
-
-    ![Image of set data privacy](images/power-bi-set-data-privacy.png)
-
-- View the results of your query
-
-    ![Image of query results](images/power-bi-query-results.png)
-
-## Related topic
-- [Create custom Power BI reports with user authentication](run-advanced-query-sample-power-bi-user-token.md)
-- [Microsoft Defender ATP APIs](apis-intro.md)
-- [Advanced Hunting API](run-advanced-query-api.md)
-- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
-- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)

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

@@ -117,4 +117,3 @@ $results | ConvertTo-Json | Set-Content file1.json
 - [Microsoft Defender ATP APIs](apis-intro.md)
 - [Advanced Hunting API](run-advanced-query-api.md)
 - [Advanced Hunting using Python](run-advanced-query-sample-python.md)
-- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)

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

@@ -146,5 +146,4 @@ outputFile.close()
 ## Related topic
 - [Microsoft Defender ATP APIs](apis-intro.md)
 - [Advanced Hunting API](run-advanced-query-api.md)
-- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
+- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
-- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)