From e0624d2b17a8dcee07acfb08f39508a773a8dc21 Mon Sep 17 00:00:00 2001 From: senthilbing Date: Tue, 18 May 2021 09:19:38 -0700 Subject: [PATCH] Update elevation docs based on editor feedback (#14416) * update elevation docs based on editor feedback * Update based on PR feedback * Update based on feedback --- .../DEM/preview/1.0/elevation.json | 50 +++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/specification/maps/data-plane/Microsoft.Maps/DEM/preview/1.0/elevation.json b/specification/maps/data-plane/Microsoft.Maps/DEM/preview/1.0/elevation.json index 1972c4b04630..d5cbc47fbca0 100644 --- a/specification/maps/data-plane/Microsoft.Maps/DEM/preview/1.0/elevation.json +++ b/specification/maps/data-plane/Microsoft.Maps/DEM/preview/1.0/elevation.json @@ -19,14 +19,14 @@ "type": "oauth2", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "flow": "implicit", - "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure Role Based Access](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure Role based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Note\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* The `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* The Azure role based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, Powershell, CLI, Azure SDKs, or REST APIs.\n* Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently Azure Active Directory [v1.0](https://docs.microsoft.com/en-us/azure/active-directory/develop/azure-ad-endpoint-comparison) tokens are supported.", + "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0](https://docs.microsoft.com/en-us/azure/active-directory/develop/azure-ad-endpoint-comparison) tokens are supported.", "scopes": { "user_impersonation": "Impersonates a user's Azure Active Directory account." } }, "apiKeyQuery": { "type": "apiKey", - "description": "This is a shared key which is provisioned when creating an [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane via Azure portal, Powershell, CLI, Azure SDKs, or REST APIs. With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for. For publicly exposed applications our recommendation is to use server to server access of Azure Maps REST APIs where this key can be securely stored.", + "description": "This is a shared key that is provisioned when creating an [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n\n With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for.\n\n For publicly exposed applications, our recommendation is to use server-to-server access of Azure Maps REST APIs where this key can be securely stored.", "name": "subscription-key", "in": "query" } @@ -48,7 +48,7 @@ "x-ms-error-response": true }, "401": { - "description": "Access denied due to invalid subscription key or invalid Azure Active Directory bearer token. Make sure to provide a valid key for an active Azure subscription and Maps resource. Otherwise, verify the [WWW-Authenticate](https://tools.ietf.org/html/rfc6750#section-3.1) header for error code and description of the provided AAD bearer token.", + "description": "Access denied due to invalid subscription key or invalid Azure Active Directory (Azure AD) bearer token. Make sure to provide a valid key for an active Azure subscription and Maps resource. Otherwise, verify the [WWW-Authenticate](https://tools.ietf.org/html/rfc6750#section-3.1) header for error code and description of the provided Azure AD bearer token.", "schema": { "$ref": "#/definitions/ODataErrorResponse" }, @@ -85,7 +85,7 @@ "parameters": { "ClientId": { "name": "x-ms-client-id", - "description": "Specifies which account is intended for usage in conjunction with the Azure AD security model. It represents a unique ID for the Azure Maps account and can be retrieved from Azure Maps management plane Account API. To use Azure AD security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance.", + "description": "Specifies which account is intended for usage in conjunction with the Azure AD security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Azure AD security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance.", "type": "string", "in": "header", "required": false, @@ -133,8 +133,8 @@ "paths": { "/elevation/point/{format}": { "get": { - "summary": "Get elevation data on one or more points.", - "description": "**Applies to**: S1 pricing tier.\nThe Get Data for Points API provides elevation data for one or more points. A point is defined in lat,long coordinate format. Due to the URL character length limit of 2048, it's not possible to pass more than 100 coordinates as a pipeline delimited string in a URL GET request. If you intend to pass more than 100 coordinates as a pipeline delimited string, use the [POST Data\n For Points](https://docs.microsoft.com/en-us/rest/api/maps/elevation/postdataforpoints).", + "summary": "Get Elevation Data on One or More Points", + "description": "**Applies to**: S1 pricing tier.\n\nThe Get Data for Points API provides elevation data for one or more points. A point is defined in lat,long coordinate format.\n\n Due to the URL character length limit of 2048, it's not possible to pass more than 100 coordinates as a pipeline delimited string in a URL GET request. If you intend to pass more than 100 coordinates as a pipeline delimited string, use the [POST Data\n For Points](https://docs.microsoft.com/en-us/rest/api/maps/elevation/postdataforpoints).", "operationId": "Elevation_GetDataForPoints", "x-ms-examples": { "GetDataForPoints": { @@ -198,8 +198,8 @@ } }, "post": { - "summary": "Query elevation data for multiple points.", - "description": "**Applies to**: S1 pricing tier.\nThe Post Data for Points API provides elevation data for multiple points. A point is defined in lat/lon coordinate format. Use the POST endpoint only if you intend to pass multiple points in the request. If you intend to pass a single coordinate into the API, use the [GET Data For Points API](https://docs.microsoft.com/en-us/rest/api/maps/elevation/getdataforpoints).", + "summary": "Query Elevation Data for Multiple Points", + "description": "**Applies to**: S1 pricing tier.\n\nThe Post Data for Points API provides elevation data for multiple points. A point is defined in lat/lon coordinate format. Use the POST endpoint only if you intend to pass multiple points in the request. If you intend to pass a single coordinate into the API, use the [GET Data For Points API](https://docs.microsoft.com/en-us/rest/api/maps/elevation/getdataforpoints).", "operationId": "Elevation_PostDataForPoints", "x-ms-examples": { "PostDataForPoints": { @@ -259,8 +259,8 @@ }, "/elevation/line/{format}": { "get": { - "summary": "Get elevation data along a polyline.", - "description": "**Applies to**: S1 pricing tier.\n\nThe Get Data for Polyline API provides elevation data along a polyline. A polyline is defined by passing in between 2 and N endpoint coordinates separated by a pipe ('|') character. In addition to passing in endpoints, customers can specify number of sample points that will be used to divide polyline into equally spaced segments. Elevation data at both start and end points and equally spaced points along the polyline will be returned. A line between two endpoints is a straight Cartesian line, the shortest line between those two points in the coordinate reference system. Note that the point is chosen based on Euclidean distance and may markedly differ from the geodesic path along the curved surface of the reference ellipsoid.", + "summary": "Get Elevation Data Along a Polyline", + "description": "**Applies to**: S1 pricing tier.\n\nThe Get Data for Polyline API provides elevation data along a polyline.\n\n A polyline is defined by passing in between 2 and N endpoint coordinates separated by a pipe ('|') character. In addition to passing in endpoints, customers can specify the number of sample points that will be used to divide polyline into equally spaced segments. Elevation data at both start and endpoints and equally spaced points along the polyline will be returned.\n\n A line between two endpoints is a straight Cartesian line, the shortest line between those two points in the coordinate reference system. Note that the point is chosen based on Euclidean distance and may markedly differ from the geodesic path along the curved surface of the reference ellipsoid.", "operationId": "Elevation_GetDataForPolyline", "x-ms-examples": { "GetDataForPolyLine": { @@ -283,7 +283,7 @@ { "name": "lines", "in": "query", - "description": "The string representation of a polyline path. A polyline is defined by endpoint coordinates, with each endpoint separated by a pipe ('|') character. The polyline should be defined in the following format: [longitude_point1, latitude_point1 | longitude_point2, latitude_point2, ..., longitude_pointN, latitude_pointN]. The longitude and latitude values refer to the World Geodetic System (WGS84) coordinate reference system. The resolution of the data used to compute the elevation will depend on the distance between the endpoints.", + "description": "The string representation of a polyline path. A polyline is defined by endpoint coordinates, with each endpoint separated by a pipe ('|') character. The polyline should be defined in the following format: `[longitude_point1, latitude_point1 | longitude_point2, latitude_point2, ..., longitude_pointN, latitude_pointN]`.\n\n The longitude and latitude values refer to the World Geodetic System (WGS84) coordinate reference system. The resolution of the data used to compute the elevation depends on the distance between the endpoints.", "required": true, "type": "array", "collectionFormat": "pipes", @@ -298,7 +298,7 @@ { "name": "samples", "in": "query", - "description": "The samples parameter specifies the number of equally spaced points at which elevation values should be provided along a polyline path. The number of samples should range from 2 to 2,000. Default value is 10 if not provided.", + "description": "The samples parameter specifies the number of equally spaced points at which elevation values should be provided along a polyline path. The number of samples should range from 2 to 2,000. Default value is 10.", "type": "number", "minimum": 2, "maximum": 2000, @@ -334,8 +334,8 @@ } }, "post": { - "summary": "Query elevation data along a polyline.", - "description": "**Applies to**: S1 pricing tier.\nThe Post Data for Polyline API provides elevation data along a polyline. A polyline is defined by passing in between 2 and N endpoint coordinates separated by a pipe ('|') character. In addition to passing in endpoints, customers can specify number of sample points that will be used to divide polyline into equally spaced segments. Elevation data at both start and end points and equally spaced points along the polyline will be returned. A line between two endpoints is a straight Cartesian line, the shortest line between those two points in the coordinate reference system. Note that the point is chosen based on Euclidean distance and may markedly differ from the geodesic path along the curved surface of the reference ellipsoid.", + "summary": "Query Elevation Data Along a Polyline", + "description": "**Applies to**: S1 pricing tier.\n\n The Post Data for Polyline API provides elevation data along a polyline. A polyline is defined by passing in between 2 and N endpoint coordinates separated by a pipe ('|') character. In addition to passing in endpoints, customers can specify the number of sample points that will be used to divide polyline into equally spaced segments.\n\n Elevation data at both start and end points and equally spaced points along the polyline will be returned. A line between two endpoints is a straight Cartesian line, the shortest line between those two points in the coordinate reference system. Note that the point is chosen based on Euclidean distance and may markedly differ from the geodesic path along the curved surface of the reference ellipsoid.", "operationId": "Elevation_PostDataForPolyline", "x-ms-examples": { "PostDataForPolyLine": { @@ -358,7 +358,7 @@ { "name": "linesRequestBody", "in": "body", - "description": "The string representation of a polyline path. A polyline is defined by endpoint coordinates, with each endpoint separated by a pipe ('|') character. The polyline should be defined in the following format: [longitude_point1, latitude_point1 | longitude_point2, latitude_point2, ..., longitude_pointN, latitude_pointN]. The longitude and latitude values refer to the World Geodetic System (WGS84) coordinate reference system. The resolution of the data used to compute the elevation will depend on the distance between the endpoints.", + "description": "The string representation of a polyline path. A polyline is defined by endpoint coordinates, with each endpoint separated by a pipe ('|') character. The polyline should be defined in the following format: `[longitude_point1, latitude_point1 | longitude_point2, latitude_point2, ..., longitude_pointN, latitude_pointN]`. The longitude and latitude values refer to the World Geodetic System (WGS84) coordinate reference system. The resolution of the data used to compute the elevation will depend on the distance between the endpoints.", "required": true, "schema": { "$ref": "#/definitions/LinesInRequestBody" @@ -367,7 +367,7 @@ { "name": "samples", "in": "query", - "description": "The samples parameter specifies the number of equally spaced points at which elevation values should be provided along a polyline path. The number of samples should range from 2 to 2,000. Default value is 10 if not provided.", + "description": "The samples parameter specifies the number of equally spaced points at which elevation values should be provided along a polyline path. The number of samples should range from 2 to 2,000. Default value is 10.", "type": "number", "minimum": 2, "maximum": 2000, @@ -405,8 +405,8 @@ }, "/elevation/lattice/{format}": { "get": { - "summary": "Get elevation data at equally-spaced locations within a bounding box.", - "description": "**Applies to**: S1 pricing tier.\n\nThe Get Data for Bounding Box API provides elevation data at equally-spaced locations within a bounding box. A bounding box is defined by the coordinates for two corners (southwest, northeast) and then subsequently divided into rows and columns. Elevations are returned for the vertices of the grid created by the rows and columns. Up to 2000 elevations can be returned in a single request. The returned elevation values are ordered, starting at the southwest corner, and then proceeding west to east along the row. At the end of the row, it moves north to the next row, and repeats the process until it reaches the far northeast corner.", + "summary": "Get Elevation Data at Equally Spaced Locations Within a Bounding Box", + "description": "**Applies to**: S1 pricing tier.\n\nThe Get Data for Bounding Box API provides elevation data at equally spaced locations within a bounding box. A bounding box is defined by the coordinates for two corners (southwest, northeast) and then subsequently divided into rows and columns.\n\n Elevations are returned for the vertices of the grid created by the rows and columns. Up to 2,000 elevations can be returned in a single request. The returned elevation values are ordered, starting at the southwest corner, and then proceeding west to east along the row. At the end of the row, it moves north to the next row, and repeats the process until it reaches the far northeast corner.", "operationId": "Elevation_GetDataForBoundingBox", "x-ms-examples": { "GetDataForBoundingBox": { @@ -429,7 +429,7 @@ { "name": "bounds", "in": "query", - "description": "The string that represents the rectangular area of a bounding box. The bounds parameter is defined by the 4 bounding box coordinates, with WGS84 longitude and latitude of the southwest corner followed by WGS84 longitude and latitude of the northeast corner. The string is presented in the following format: [SouthwestCorner_Longitude, SouthwestCorner_Latitude, NortheastCorner_Longitude, NortheastCorner_Latitude].", + "description": "The string that represents the rectangular area of a bounding box. The bounds parameter is defined by the 4 bounding box coordinates, with WGS84 longitude and latitude of the southwest corner followed by WGS84 longitude and latitude of the northeast corner. The string is presented in the following format: `[SouthwestCorner_Longitude, SouthwestCorner_Latitude, NortheastCorner_Longitude, NortheastCorner_Latitude]`.", "required": true, "type": "array", "collectionFormat": "csv", @@ -440,7 +440,7 @@ { "name": "rows", "in": "query", - "description": "Specifies the number of rows to use to divide the bounding box area into a grid. The number of vertices in the grid should be less than 2000. ", + "description": "Specifies the number of rows to use to divide the bounding box area into a grid. The number of vertices in the grid should be less than 2,000. ", "type": "number", "minimum": 2, "maximum": 1000, @@ -449,7 +449,7 @@ { "name": "columns", "in": "query", - "description": "Specifies the number of columns to use to divide the bounding box area into a grid. The number of vertices in the grid should be less than 2000. ", + "description": "Specifies the number of columns to use to divide the bounding box area into a grid. The number of vertices in the grid should be less than 2,000. ", "type": "number", "minimum": 2, "maximum": 1000, @@ -488,7 +488,7 @@ "definitions": { "ODataErrorResponse": { "type": "object", - "description": "This response object is returned when an error occurs in the Maps API.", + "description": "This response object is returned when an error occurs in the Azure Maps API.", "properties": { "error": { "$ref": "#/definitions/ODataError" @@ -497,7 +497,7 @@ }, "ODataError": { "type": "object", - "description": "This object is returned when an error occurs in the Maps API.", + "description": "This object is returned when an error occurs in the Azure Maps API.", "properties": { "code": { "type": "string", @@ -507,7 +507,7 @@ "message": { "type": "string", "readOnly": true, - "description": "If available, a human readable description of the error." + "description": "If available, a human-readable description of the error." }, "details": { "type": "array", @@ -587,7 +587,7 @@ } }, "ElevationLatticeResponse": { - "description": "The response from the Get Data for Bounding Box API. The results will be ordered starting with the southwest corner, and then proceed west to east and south to north.", + "description": "The response from the Get Data for Bounding Box API. The results are ordered starting with the southwest corner, and then proceed west to east and south to north.", "type": "array", "readOnly": true, "items": {