Network Watchers - Get Azure Reachability Report

Reference

Service:: Network Watcher

API Version:: 2023-09-01

NOTE: This feature is currently in preview and still being tested for stability. Gets the relative latency score for internet service providers from a specified location to Azure regions.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/networkWatchers/{networkWatcherName}/azureReachabilityReport?api-version=2023-09-01

URI Parameters

Name	In	Required	Type	Description
networkWatcherName	path	True	string	The name of the network watcher resource.
resourceGroupName	path	True	string	The name of the network watcher resource group.
subscriptionId	path	True	string	The subscription credentials which uniquely identify the Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.
api-version	query	True	string	Client API version.

Request Body

Name	Required	Type	Description
endTime	True	string	The end time for the Azure reachability report.
providerLocation	True	AzureReachabilityReportLocation	Parameters that define a geographic location.
startTime	True	string	The start time for the Azure reachability report.
azureLocations		string[]	Optional Azure regions to scope the query to.
providers		string[]	List of Internet service providers.

Responses

Name	Type	Description
200 OK	AzureReachabilityReport	Successful request for Azure reachability report.
202 Accepted	AzureReachabilityReport	Accepted and the operation will complete asynchronously.
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Get Azure Reachability Report

Sample Request

POST https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/networkWatchers/nw1/azureReachabilityReport?api-version=2023-09-01

{
  "providerLocation": {
    "country": "United States",
    "state": "washington"
  },
  "providers": [
    "Frontier Communications of America, Inc. - ASN 5650"
  ],
  "azureLocations": [
    "West US"
  ],
  "startTime": "2017-09-07T00:00:00Z",
  "endTime": "2017-09-10T00:00:00Z"
}


import com.azure.resourcemanager.network.models.AzureReachabilityReportLocation;
import com.azure.resourcemanager.network.models.AzureReachabilityReportParameters;
import java.time.OffsetDateTime;
import java.util.Arrays;

/**
 * Samples for NetworkWatchers GetAzureReachabilityReport.
 */
public final class Main {
    /*
     * x-ms-original-file: specification/network/resource-manager/Microsoft.Network/stable/2023-09-01/examples/
     * NetworkWatcherAzureReachabilityReportGet.json
     */
    /**
     * Sample code: Get Azure Reachability Report.
     * 
     * @param azure The entry point for accessing resource management APIs in Azure.
     */
    public static void getAzureReachabilityReport(com.azure.resourcemanager.AzureResourceManager azure) {
        azure.networks().manager().serviceClient().getNetworkWatchers().getAzureReachabilityReport("rg1", "nw1",
            new AzureReachabilityReportParameters()
                .withProviderLocation(
                    new AzureReachabilityReportLocation().withCountry("United States").withState("washington"))
                .withProviders(Arrays.asList("Frontier Communications of America, Inc. - ASN 5650"))
                .withAzureLocations(Arrays.asList("West US"))
                .withStartTime(OffsetDateTime.parse("2017-09-07T00:00:00Z"))
                .withEndTime(OffsetDateTime.parse("2017-09-10T00:00:00Z")),
            com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

from azure.identity import DefaultAzureCredential
from azure.mgmt.network import NetworkManagementClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-network
# USAGE
    python network_watcher_azure_reachability_report_get.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = NetworkManagementClient(
        credential=DefaultAzureCredential(),
        subscription_id="subid",
    )

    response = client.network_watchers.begin_get_azure_reachability_report(
        resource_group_name="rg1",
        network_watcher_name="nw1",
        parameters={
            "azureLocations": ["West US"],
            "endTime": "2017-09-10T00:00:00Z",
            "providerLocation": {"country": "United States", "state": "washington"},
            "providers": ["Frontier Communications of America, Inc. - ASN 5650"],
            "startTime": "2017-09-07T00:00:00Z",
        },
    ).result()
    print(response)


# x-ms-original-file: specification/network/resource-manager/Microsoft.Network/stable/2023-09-01/examples/NetworkWatcherAzureReachabilityReportGet.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

package armnetwork_test

import (
	"context"
	"log"

	"time"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/network/armnetwork/v5"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/d4205894880b989ede35d62d97c8e901ed14fb5a/specification/network/resource-manager/Microsoft.Network/stable/2023-09-01/examples/NetworkWatcherAzureReachabilityReportGet.json
func ExampleWatchersClient_BeginGetAzureReachabilityReport() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armnetwork.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	poller, err := clientFactory.NewWatchersClient().BeginGetAzureReachabilityReport(ctx, "rg1", "nw1", armnetwork.AzureReachabilityReportParameters{
		AzureLocations: []*string{
			to.Ptr("West US")},
		EndTime: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2017-09-10T00:00:00.000Z"); return t }()),
		ProviderLocation: &armnetwork.AzureReachabilityReportLocation{
			Country: to.Ptr("United States"),
			State:   to.Ptr("washington"),
		},
		Providers: []*string{
			to.Ptr("Frontier Communications of America, Inc. - ASN 5650")},
		StartTime: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2017-09-07T00:00:00.000Z"); return t }()),
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	res, err := poller.PollUntilDone(ctx, nil)
	if err != nil {
		log.Fatalf("failed to pull the result: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.AzureReachabilityReport = armnetwork.AzureReachabilityReport{
	// 	AggregationLevel: to.Ptr("State"),
	// 	ProviderLocation: &armnetwork.AzureReachabilityReportLocation{
	// 		Country: to.Ptr("United States"),
	// 		State: to.Ptr("washington"),
	// 	},
	// 	ReachabilityReport: []*armnetwork.AzureReachabilityReportItem{
	// 		{
	// 			AzureLocation: to.Ptr("West US"),
	// 			Latencies: []*armnetwork.AzureReachabilityReportLatencyInfo{
	// 				{
	// 					Score: to.Ptr[int32](94),
	// 					TimeStamp: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2017-09-07T00:00:00.000Z"); return t}()),
	// 				},
	// 				{
	// 					Score: to.Ptr[int32](94),
	// 					TimeStamp: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2017-09-08T00:00:00.000Z"); return t}()),
	// 				},
	// 				{
	// 					Score: to.Ptr[int32](94),
	// 					TimeStamp: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2017-09-09T00:00:00.000Z"); return t}()),
	// 			}},
	// 			Provider: to.Ptr("Frontier Communications of America, Inc. - ASN 5650"),
	// 	}},
	// }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

const { NetworkManagementClient } = require("@azure/arm-network");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to NOTE: This feature is currently in preview and still being tested for stability. Gets the relative latency score for internet service providers from a specified location to Azure regions.
 *
 * @summary NOTE: This feature is currently in preview and still being tested for stability. Gets the relative latency score for internet service providers from a specified location to Azure regions.
 * x-ms-original-file: specification/network/resource-manager/Microsoft.Network/stable/2023-09-01/examples/NetworkWatcherAzureReachabilityReportGet.json
 */
async function getAzureReachabilityReport() {
  const subscriptionId = process.env["NETWORK_SUBSCRIPTION_ID"] || "subid";
  const resourceGroupName = process.env["NETWORK_RESOURCE_GROUP"] || "rg1";
  const networkWatcherName = "nw1";
  const parameters = {
    azureLocations: ["West US"],
    endTime: new Date("2017-09-10T00:00:00Z"),
    providerLocation: { country: "United States", state: "washington" },
    providers: ["Frontier Communications of America, Inc. - ASN 5650"],
    startTime: new Date("2017-09-07T00:00:00Z"),
  };
  const credential = new DefaultAzureCredential();
  const client = new NetworkManagementClient(credential, subscriptionId);
  const result = await client.networkWatchers.beginGetAzureReachabilityReportAndWait(
    resourceGroupName,
    networkWatcherName,
    parameters,
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

using System;
using System.Threading.Tasks;
using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Network;
using Azure.ResourceManager.Network.Models;
using Azure.ResourceManager.Resources;

// Generated from example definition: specification/network/resource-manager/Microsoft.Network/stable/2023-09-01/examples/NetworkWatcherAzureReachabilityReportGet.json
// this example is just showing the usage of "NetworkWatchers_GetAzureReachabilityReport" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this NetworkWatcherResource created on azure
// for more information of creating NetworkWatcherResource, please refer to the document of NetworkWatcherResource
string subscriptionId = "subid";
string resourceGroupName = "rg1";
string networkWatcherName = "nw1";
ResourceIdentifier networkWatcherResourceId = NetworkWatcherResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, networkWatcherName);
NetworkWatcherResource networkWatcher = client.GetNetworkWatcherResource(networkWatcherResourceId);

// invoke the operation
AzureReachabilityReportContent content = new AzureReachabilityReportContent(new AzureReachabilityReportLocation("United States")
{
    State = "washington",
}, DateTimeOffset.Parse("2017-09-07T00:00:00Z"), DateTimeOffset.Parse("2017-09-10T00:00:00Z"))
{
    Providers =
    {
    "Frontier Communications of America, Inc. - ASN 5650"
    },
    AzureLocations =
    {
    new AzureLocation("West US")
    },
};
ArmOperation<AzureReachabilityReport> lro = await networkWatcher.GetAzureReachabilityReportAsync(WaitUntil.Completed, content);
AzureReachabilityReport result = lro.Value;

Console.WriteLine($"Succeeded: {result}");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample Response

Status code:: 200

{
  "aggregationLevel": "State",
  "providerLocation": {
    "country": "United States",
    "state": "washington"
  },
  "reachabilityReport": [
    {
      "provider": "Frontier Communications of America, Inc. - ASN 5650",
      "azureLocation": "West US",
      "latencies": [
        {
          "timeStamp": "2017-09-07T00:00:00Z",
          "score": 94
        },
        {
          "timeStamp": "2017-09-08T00:00:00Z",
          "score": 94
        },
        {
          "timeStamp": "2017-09-09T00:00:00Z",
          "score": 94
        }
      ]
    }
  ]
}

Status code:: 202

Location: https:/management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/networkWatchers/nw1/azureReachabilityReport?api-version=2023-09-01

Response Body

{
  "aggregationLevel": "State",
  "providerLocation": {
    "country": "United States",
    "state": "washington"
  },
  "reachabilityReport": [
    {
      "provider": "Frontier Communications of America, Inc. - ASN 5650",
      "azureLocation": "West US",
      "latencies": [
        {
          "timeStamp": "2017-09-07T00:00:00Z",
          "score": 94
        },
        {
          "timeStamp": "2017-09-08T00:00:00Z",
          "score": 94
        },
        {
          "timeStamp": "2017-09-09T00:00:00Z",
          "score": 94
        }
      ]
    }
  ]
}

Definitions

Name	Description
AzureReachabilityReport	Azure reachability report details.
AzureReachabilityReportItem	Azure reachability report details for a given provider location.
AzureReachabilityReportLatencyInfo	Details on latency for a time series.
AzureReachabilityReportLocation	Parameters that define a geographic location.
AzureReachabilityReportParameters	Geographic and time constraints for Azure reachability report.
ErrorDetails	Common error details representation.
ErrorResponse	The error object.

AzureReachabilityReport

Azure reachability report details.

Name	Type	Description
aggregationLevel	string	The aggregation level of Azure reachability report. Can be Country, State or City.
providerLocation	AzureReachabilityReportLocation	Parameters that define a geographic location.
reachabilityReport	AzureReachabilityReportItem[]	List of Azure reachability report items.

AzureReachabilityReportItem

Azure reachability report details for a given provider location.

Name	Type	Description
azureLocation	string	The Azure region.
latencies	AzureReachabilityReportLatencyInfo[]	List of latency details for each of the time series.
provider	string	The Internet service provider.

AzureReachabilityReportLatencyInfo

Details on latency for a time series.

Name	Type	Description
score	integer	The relative latency score between 1 and 100, higher values indicating a faster connection.
timeStamp	string	The time stamp.

AzureReachabilityReportLocation

Parameters that define a geographic location.

Name	Type	Description
city	string	The name of the city or town.
country	string	The name of the country.
state	string	The name of the state.

AzureReachabilityReportParameters

Geographic and time constraints for Azure reachability report.

Name	Type	Description
azureLocations	string[]	Optional Azure regions to scope the query to.
endTime	string	The end time for the Azure reachability report.
providerLocation	AzureReachabilityReportLocation	Parameters that define a geographic location.
providers	string[]	List of Internet service providers.
startTime	string	The start time for the Azure reachability report.

ErrorDetails

Common error details representation.

Name	Type	Description
code	string	Error code.
message	string	Error message.
target	string	Error target.

ErrorResponse

The error object.

Name	Type	Description
error	ErrorDetails	Error The error details object.