API Long-Running операции создателя (Предварительная версия)Creator (Preview) Long-Running Operation API

• 12/07/2020
• Чтение занимает 2 мин
• • a
  • o

Некоторые API в Azure Maps используют шаблон асинхронного Request-Reply.Some APIs in Azure Maps use an Asynchronous Request-Reply pattern. Этот шаблон позволяет Azure Maps предоставлять высокодоступные и быстро реагирующие службы.This pattern allows Azure Maps to provide highly available and responsive services. В этой статье описывается характерная для Azure Maps реализация длительной асинхронной фоновой обработки.This article explains Azure Map's specific implementation of long-running asynchronous background processing.

Отправка запросаSubmitting a request

Клиентское приложение запускает длительную операцию с помощью синхронного вызова к API HTTP.A client application starts a long-running operation through a synchronous call to an HTTP API. Как правило, такой вызов поступает в виде HTTP-запроса POST.Typically, this call is in the form of an HTTP POST request. При успешном создании асинхронной рабочей нагрузки API возвращает код состояния HTTP 202, сообщающий о том, что запрос принят.When an asynchronous workload is successfully created, the API will return an HTTP 202 status code, indicating that the request has been accepted. Этот ответ содержит заголовок Location, указывающий на конечную точку, которую клиент может опрашивать для проверки состояния длительной операции.This response contains a Location header pointing to an endpoint that the client can poll to check the status of the long-running operation.

Пример ответа, сообщающего об успешном принятии и обработке запросаExample of a success response

Status: 202 Accepted
Location: https://atlas.microsoft.com/service/operations/{operationId}

Если вызов не проходит проверку, API вместо этого возвращает ответ HTTP 400, сообщающий о недопустимом запросе.If the call doesn't pass validation, the API will instead return an HTTP 400 response for a Bad Request. Текст ответа содержит для клиента дополнительные сведения о том, почему запрос является недопустимым.The response body will provide the client more information on why the request was invalid.

Мониторинг состояния операцииMonitoring the operation status

Чтобы проверить состояние длительной операции, можно опросить конечную точку расположения, указанную в заголовке принятого ответа.The location endpoint provided in the accepted response headers can be polled to check the status of the long-running operation. Текст ответа из запроса о состоянии операции всегда будет содержать свойства status и createdDateTime.The response body from operation status request will always contain the status and the createdDateTime properties. Свойство status представляет текущее состояние длительной операции.The status property shows the current state of the long-running operation. Возможные значения включают "NotStarted", "Running", "Succeeded" и "Failed".Possible states include "NotStarted", "Running", "Succeeded", and "Failed". Свойство createdDateTime представляет время выполнения первоначального запроса для запуска длительной операции.The createdDateTime property shows the time the initial request was made to start the long-running operation. Если состояние имеет значение "NotStarted" или "Running", в ответе также будет указан заголовок Retry-After.When the state is either "NotStarted" or "Running", a Retry-After header will also be provided with the response. Заголовок Retry-After, представляющий время в секундах, позволяет определить, когда следует выполнить следующий опрашивающий вызов к API состояния операции.The Retry-After header, measured in seconds, can be used to determine when the next polling call to the operation status API should be made.

Пример ответа с информацией о состоянииExample of running a status response

Status: 200 OK
Retry-After: 30
{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "createdDateTime": "3/11/2020 8:45:13 PM +00:00",
    "status": "Running"
}

Обработка завершения операцийHandling operation completion

После завершения длительной операции состояние ответа будет "Succeeded" или "Failed".Upon completing the long-running operation, the status of the response will either be "Succeeded" or "Failed". Если новый ресурс был создан в ходе длительной операции, ответ с информацией об успешном принятии и обработке запроса будет содержать код состояния HTTP 201 Created.When a new resource has been created from a long-running operation, the success response will return an HTTP 201 Created status code. Ответ также будет содержать заголовок Location, указывающий на метаданные ресурса.The response will also contain a Location header that points to metadata about the resource. Если новый ресурс не был создан, ответ будет содержать код состояния HTTP 200 OK.When no new resource has been created, the success response will return an HTTP 200 OK status code. Хотя в случае ошибки ответ также будет содержать код состояния 200 OK,Upon a failure, the response status code will also be the 200 OKcode. в тексте также будет присутствовать свойство error.However, the response will have an error property in the body. Данные об ошибках соответствуют спецификации ошибок OData.The error data adheres to the OData error specification.

Пример ответа с информацией об успешном выполненииExample of success response

Status: 201 Created
Location: "https://atlas.microsoft.com/tileset/{tileset-id}"
 {
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "createdDateTime": "3/11/2020 8:45:13 PM +00:00",
    "status": "Succeeded",
    "resourceLocation": "https://atlas.microsoft.com/tileset/{tileset-id}"
}

Пример ответа с информацией об ошибке при принятии и обработке запросаExample of failure response

Status: 200 OK

{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "createdDateTime": "3/11/2020 8:45:13 PM +00:00",
    "status": "Failed",
    "error": {
        "code": "InvalidFeature",
        "message": "The provided feature is invalid.",
        "details": {
            "code": "NoGeometry",
            "message": "No geometry was provided with the feature."
        }
    }
}