Skip to content

Commit bb737a1

Browse files
alextts627alextts627
authored
[Azure Maps] GeoLocation API review (Azure#30547)
Dotnet Geolocation SDK
1 parent 350a6d8 commit bb737a1

39 files changed

+1432
-1
lines changed

‎sdk/maps/Azure.Maps.GeoLocation/CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Release History
2+
3+
## 1.0.0-beta.1 (2022-09-06)
4+
5+
### Features Added
6+
7+
- Initial release

‎sdk/maps/Azure.Maps.GeoLocation/Directory.Build.props‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
2+
<!--
3+
Add any shared properties you want for the projects under this package directory that need to be set before the auto imported Directory.Build.props
4+
-->
5+
<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory).., Directory.Build.props))\Directory.Build.props" />
6+
</Project>

‎sdk/maps/Azure.Maps.GeoLocation/README.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Azure Maps GeoLocation client library for .NET
2+
3+
Azure Maps GeoLocation is a library that can find geolocation to a location or points of interest.
4+
5+
[Source code](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/maps/Azure.Maps.GeoLocation/src) | [API reference documentation](https://docs.microsoft.com/rest/api/maps/) | [REST API reference documentation](https://docs.microsoft.com/rest/api/maps/geolocation) | [Product documentation](https://docs.microsoft.com/azure/azure-maps/)
6+
7+
## Getting started
8+
9+
### Install the package
10+
11+
Install the client library for .NET with [NuGet](https://www.nuget.org/):
12+
13+
```dotnetcli
14+
dotnet add package Azure.Maps.GeoLocation --prerelease
15+
```
16+
17+
### Prerequisites
18+
19+
> You must have an [Azure subscription](https://azure.microsoft.com/free/dotnet/) and [Azure Maps account](https://docs.microsoft.com/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account).
20+
21+
To create a new Azure Maps account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:
22+
23+
```powershell
24+
az maps account create --kind "Gen2" --disable-local-auth true --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2" --accept-tos
25+
```
26+
27+
### Authenticate the client
28+
29+
There are 2 ways to authenticate the client: Shared key authentication and Azure AD.
30+
31+
#### Shared Key authentication
32+
33+
* Go to Azure Maps account > Authentication tab
34+
* Copy `Primary Key` or `Secondary Key` under **Shared Key Authentication** section
35+
36+
```C# Snippet:InstantiateGeoLocationClientViaSubscriptionKey
37+
// Create a MapsGeoLocationClient that will authenticate through Subscription Key (Shared key)
38+
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
39+
MapsGeoLocationClient client = new MapsGeoLocationClient(credential);
40+
```
41+
42+
#### Azure AD authentication
43+
44+
In order to interact with the Azure Maps service, you'll need to create an instance of the `MapsGeoLocationClient` class. The [Azure Identity library](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity/README.md) makes it easy to add Azure Active Directory support for authenticating Azure SDK clients with their corresponding Azure services.
45+
46+
To use AAD authentication, set the environment variables as described in the [Azure Identity README](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity/README.md) and create a `DefaultAzureCredential` instance to use with the `MapsRouteClient`.
47+
48+
We also need **Azure Maps Client ID** which can get from Azure Maps page > Authentication tab > "Client ID" in Azure Active Directory Authentication section.
49+
50+
```C# Snippet:InstantiateGeoLocationClientViaAAD
51+
// Create a MapsGeoLocationClient that will authenticate through Active Directory
52+
TokenCredential credential = new DefaultAzureCredential();
53+
string clientId = "<Your Map ClientId>";
54+
MapsGeoLocationClient client = new MapsGeoLocationClient(credential, clientId);
55+
```
56+
57+
## Key concepts
58+
59+
`MapsGeoLocationClient` is designed for:
60+
61+
* Communicate with Azure Maps GeoLocation SDK endpoint to get location from given IP address
62+
63+
Learn more about examples in [samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/maps/Azure.Maps.GeoLocation/samples)
64+
65+
### Thread safety
66+
67+
We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads.
68+
69+
### Additional concepts
70+
<!-- CLIENT COMMON BAR -->
71+
[Client options](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) |
72+
[Accessing the response](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#accessing-http-response-details-using-responset) |
73+
[Long-running operations](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#consuming-long-running-operations-using-operationt) |
74+
[Handling failures](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#reporting-errors-requestfailedexception) |
75+
[Diagnostics](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md) |
76+
[Mocking](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#mocking) |
77+
[Client lifetime](https://devblogs.microsoft.com/azure-sdk/lifetime-management-and-thread-safety-guarantees-of-azure-sdk-net-clients/)
78+
<!-- CLIENT COMMON BAR -->
79+
80+
## Examples
81+
82+
You can familiarize yourself with different APIs using our [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/maps/Azure.Maps.GeoLocation/samples).
83+
84+
Before calling geolocation APIs, instantiate a `MapsGeoLocationClient` first. Below example uses AAD to create the client instance:
85+
86+
```C# Snippet:InstantiateGeoLocationClientViaAAD
87+
// Create a MapsGeoLocationClient that will authenticate through Active Directory
88+
TokenCredential credential = new DefaultAzureCredential();
89+
string clientId = "<Your Map ClientId>";
90+
MapsGeoLocationClient client = new MapsGeoLocationClient(credential, clientId);
91+
```
92+
93+
### Get Location
94+
95+
This service will return the ISO country code for the provided IP address. Developers can use this information to block or alter certain content based on geographical locations where the application is being viewed from.
96+
97+
```C# Snippet:GetLocation
98+
//Get location by given IP address
99+
string ipAddress = "2001:4898:80e8:b::189";
100+
Response<IpAddressToLocationResult> result = client.GetLocation(ipAddress);
101+
102+
//Get location result country code
103+
Console.WriteLine($"Country code results by given IP Address: {result.Value.IsoCode}");
104+
```
105+
106+
For more detailed examples, please see [geolocation samples](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/maps/Azure.Maps.GeoLocation/samples/GetLocationSamples.md) page.
107+
108+
## Troubleshooting
109+
110+
### General
111+
112+
When you interact with the Azure Maps services, errors returned by the Language service correspond to the same HTTP status codes returned for [REST API requests](https://docs.microsoft.com/rest/api/maps/geolocation).
113+
114+
For example, if you pass wrong IP address, an error is returned, indicating "Bad Request" (HTTP Status code: 400).
115+
116+
```C# Snippet:CatchGeoLocationException
117+
try
118+
{
119+
// An invalid IP address
120+
string inValidIpAddress = "xxx";
121+
122+
Response<IpAddressToLocationResult> result = client.GetLocation(inValidIpAddress);
123+
// Do something with result ...
124+
}
125+
catch (RequestFailedException e)
126+
{
127+
Console.WriteLine(e.ToString());
128+
}
129+
```
130+
131+
## Next steps
132+
133+
* For more context and additional scenarios, please see: [More detailed samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/maps/Azure.Maps.GeoLocation/samples)
134+
135+
## Contributing
136+
137+
See the [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md) for details on building, testing, and contributing to this library.
138+
139+
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <cla.microsoft.com>.
140+
141+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
142+
143+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact <[email protected]> with any additional questions or comments.
144+
145+
![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net/sdk/template/Azure.Template/README.png)

‎sdk/maps/Azure.Maps.GeoLocation/api/Azure.Maps.GeoLocation.netstandard2.0.cs‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
namespace Azure.Maps.GeoLocation
2+
{
3+
public partial class IpAddressToLocationResult
4+
{
5+
internal IpAddressToLocationResult() { }
6+
public string IpAddress { get { throw null; } }
7+
public string IsoCode { get { throw null; } }
8+
}
9+
public partial class MapsGeoLocationClient
10+
{
11+
protected MapsGeoLocationClient() { }
12+
public MapsGeoLocationClient(Azure.AzureKeyCredential credential) { }
13+
public MapsGeoLocationClient(Azure.AzureKeyCredential credential, Azure.Maps.GeoLocation.MapsGeoLocationClientOptions options) { }
14+
public MapsGeoLocationClient(Azure.Core.TokenCredential credential, string clientId) { }
15+
public MapsGeoLocationClient(Azure.Core.TokenCredential credential, string clientId, Azure.Maps.GeoLocation.MapsGeoLocationClientOptions options) { }
16+
public virtual Azure.Response<Azure.Maps.GeoLocation.IpAddressToLocationResult> GetLocation(string ipAddress, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
17+
public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Maps.GeoLocation.IpAddressToLocationResult>> GetLocationAsync(string ipAddress, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
18+
}
19+
public partial class MapsGeoLocationClientOptions : Azure.Core.ClientOptions
20+
{
21+
public MapsGeoLocationClientOptions(Azure.Maps.GeoLocation.MapsGeoLocationClientOptions.ServiceVersion version = Azure.Maps.GeoLocation.MapsGeoLocationClientOptions.ServiceVersion.V1) { }
22+
public enum ServiceVersion
23+
{
24+
V1 = 1,
25+
}
26+
}
27+
}

‎sdk/maps/Azure.Maps.GeoLocation/samples/GetLocationSamples.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Get Location Samples
2+
3+
To use these samples, you'll first need to set up resources. See [getting started](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/maps/Azure.Maps.GeoLocation#getting-started) for details.
4+
5+
## Get Location with IP Address
6+
7+
The sample below returns the for the provided IP address:
8+
9+
```C# Snippet:GetLocation
10+
//Get location by given IP address
11+
string ipAddress = "2001:4898:80e8:b::189";
12+
Response<IpAddressToLocationResult> result = client.GetLocation(ipAddress);
13+
14+
//Get location result country code
15+
Console.WriteLine($"Country code results by given IP Address: {result.Value.IsoCode}");
16+
```

‎sdk/maps/Azure.Maps.GeoLocation/samples/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
page_type: sample
3+
languages:
4+
- csharp
5+
products:
6+
- azure
7+
- azure-maps
8+
name: Azure.Maps.GeoLocation samples for .NET
9+
description: Samples for the Azure.Maps.GeoLocation client library.
10+
---
11+
12+
# Azure.Maps.GeoLocation Samples
13+
14+
## Use Cases
15+
16+
For different APIs, please refer the following samples:
17+
18+
[Get Location](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/maps/Azure.Maps.GeoLocation/samples/GetLocationSamples.md)

‎sdk/maps/Azure.Maps.GeoLocation/src/Azure.Maps.GeoLocation.csproj‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup>
3+
<Description>Azure Maps Azure.Maps.GeoLocation</Description>
4+
<AssemblyTitle>Azure Maps Azure.Maps.GeoLocation</AssemblyTitle>
5+
<Version>1.0.0-beta.1</Version>
6+
<PackageTags>Azure;Azure Maps;Maps Azure.Maps.GeoLocation</PackageTags>
7+
<TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>
8+
<NoWarn>$(NoWarn);AZC0001;AZC0012</NoWarn>
9+
</PropertyGroup>
10+
11+
<ItemGroup>
12+
<PackageReference Include="Azure.Core" />
13+
<PackageReference Include="System.Text.Json" />
14+
</ItemGroup>
15+
16+
<!-- Shared source from Azure.Core -->
17+
<ItemGroup>
18+
<Compile Include="$(AzureCoreSharedSources)Argument.cs" Link="Shared%(RecursiveDir)%(Filename)%(Extension)" />
19+
<Compile Include="$(AzureCoreSharedSources)AppContextSwitchHelper.cs" LinkBase="Shared" />
20+
<Compile Include="$(AzureCoreSharedSources)AsyncLockWithValue.cs" LinkBase="Shared" />
21+
<Compile Include="$(AzureCoreSharedSources)AzureKeyCredentialPolicy.cs" Link="Shared%(RecursiveDir)%(Filename)%(Extension)" />
22+
<Compile Include="$(AzureCoreSharedSources)AzureResourceProviderNamespaceAttribute.cs" LinkBase="Shared" />
23+
<Compile Include="$(AzureCoreSharedSources)ClientDiagnostics.cs" LinkBase="Shared" />
24+
<Compile Include="$(AzureCoreSharedSources)ConstantDelayStrategy.cs" LinkBase="Shared" />
25+
<Compile Include="$(AzureCoreSharedSources)ContentTypeUtilities.cs" LinkBase="Shared" />
26+
<Compile Include="$(AzureCoreSharedSources)DelayStrategy.cs" LinkBase="Shared" />
27+
<Compile Include="$(AzureCoreSharedSources)DiagnosticScope.cs" LinkBase="Shared" />
28+
<Compile Include="$(AzureCoreSharedSources)DiagnosticScopeFactory.cs" LinkBase="Shared" />
29+
<Compile Include="$(AzureCoreSharedSources)ExponentialDelayStrategy.cs" LinkBase="Shared" />
30+
<Compile Include="$(AzureCoreSharedSources)HttpMessageSanitizer.cs" LinkBase="Shared" />
31+
<Compile Include="$(AzureCoreSharedSources)TaskExtensions.cs" LinkBase="Shared" />
32+
<Compile Include="$(AzureCoreSharedSources)OperationInternal.cs" LinkBase="Shared" />
33+
<Compile Include="$(AzureCoreSharedSources)OperationInternalBase.cs" LinkBase="Shared" />
34+
<Compile Include="$(AzureCoreSharedSources)OperationInternalOfT.cs" LinkBase="Shared" />
35+
<Compile Include="$(AzureCoreSharedSources)OperationPoller.cs" LinkBase="Shared" />
36+
<Compile Include="$(AzureCoreSharedSources)RetryAfterDelayStrategy.cs" LinkBase="Shared" />
37+
<Compile Include="$(AzureCoreSharedSources)VoidValue.cs" LinkBase="Shared/Core" />
38+
</ItemGroup>
39+
40+
</Project>

0 commit comments

Comments
 (0)