업데이트 메시지

Update Message 이 작업은 메시지의 가시성 제한시간을 업데이트합니다. 이 작업을 사용하여 메시지의 내용을 업데이트할 수도 있습니다. 메시지는 UTF-8 인코딩을 사용하여 XML 요청에 포함할 수 있는 형식이어야 하며 인코딩된 메시지의 크기는 최대 64KB일 수 있습니다. 이 작업은 Azure Queue Storage API 버전 2011-08-18에서 도입되었습니다.

요청

다음과 같이 요청을 구성할 Update Message 수 있습니다. HTTPS를 사용하는 것이 좋습니다. myaccount를 스토리지 계정의 이름으로 바꾸고 myqueue를 큐의 이름으로 바꿉니다.

메서드	URI 요청	HTTP 버전
`PUT`	`https://myaccount.queue.core.windows.net/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds>`	HTTP/1.1

에뮬레이트된 스토리지 서비스

이 작업은 SDK 1.6 이상 버전에서 지원됩니다.

에뮬레이트된 스토리지 서비스에 대해 요청할 때 에뮬레이터 호스트 이름 및 큐 스토리지 포트 127.0.0.1:10001를 로 지정한 다음 에뮬레이트된 스토리지 계정 이름을 지정합니다.

메서드	URI 요청	HTTP 버전
`PUT`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds>`	HTTP/1.1

URI 매개 변수

요청 URI에 다음 파라미터를 지정할 수 있습니다.

매개 변수	Description
`popreceipt`	필수 사항입니다. 메시지 가져오기 또는 메시지 업데이트 작업에 대한 이전 호출에서 반환된 유효한 팝 확인 값을 지정합니다. URL `popreceipt` 로 인코딩되어야 합니다.
`visibilitytimeout`	필수 사항입니다. 서버 시간을 기준으로 새 가시성 제한시간 값(초)을 지정합니다. 새 값은 0보다 크거나 같아야 하며 7일보다 클 수 없습니다. 메시지의 가시성 제한시간은 만료 시간보다 이후의 값으로 설정할 수 없습니다. 메시지가 삭제되거나 만료될 때까지 메시지를 업데이트할 수 있습니다.
`timeout`	Optional. 매개변수는 `timeout` 초 단위로 표시됩니다. 자세한 정보는 큐 스토리지 조작에 대한 제한시간 설정을 참조하십시오.

요청 헤더

다음 표에서는 필수 및 선택적 요청 헤더에 대해 설명합니다.

요청 헤더	Description
`Authorization`	필수 사항입니다. 권한 부여 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`Date` `or x-ms-date`	필수 사항입니다. 요청에 대한 협정 세계시(UTC)를 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`x-ms-version`	2011-08-18 이상이 필요합니다. 이 요청에 사용할 작업의 버전을 지정합니다. 자세한 내용은 Azure Storage 서비스에 대한 버전 관리를 참조하세요.
`x-ms-client-request-id`	Optional. 로깅이 구성될 때 로그에 기록되는 1KiB(KiBibyte) 문자 제한이 있는 클라이언트 생성 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 측 활동을 서버가 수신하는 요청과 상호 연관시키는 것이 좋습니다. 자세한 내용은 Azure Queue Storage 모니터링을 참조하세요.

요청 메시지 본문

요청 본문에는 다음 XML 형식의 메시지 데이터가 포함됩니다. 메시지 콘텐츠는 UTF-8로 인코딩할 수 있는 형식이어야 합니다.

<QueueMessage>  
    <MessageText>message-content</MessageText>  
</QueueMessage>

응답

응답에는 HTTP 상태 코드와 응답 헤더 집합이 포함됩니다.

상태 코드

작업이 성공하면 상태 코드 204(콘텐츠 없음)가 반환됩니다. 상태 코드에 대한 자세한 내용은 상태 및 오류 코드를 참조하세요.

응답 헤더

이 작업에 대한 응답에는 다음 헤더가 포함됩니다. 응답에는 추가 표준 HTTP 헤더가 포함될 수도 있습니다. 모든 표준 헤더는 HTTP/1.1 프로토콜 사양을 준수합니다.

요청 헤더	Description
`x-ms-request-id`	이 헤더는 작성된 요청을 고유하게 식별하며 요청 문제점을 해결하는 데 사용할 수 있습니다. 자세한 정보는 API 조작 문제 해결을 참조하십시오.
`x-ms-version`	요청을 실행하는 데 사용되는 큐 스토리지의 버전을 표시합니다. 이 헤더는 버전 2009-09-19 이상에 대한 요청에 대해 반환됩니다.
`Date`	응답이 시작된 시간을 나타내는 UTC 날짜/시간 값입니다. 서비스는 이 값을 생성합니다.
`x-ms-popreceipt`	큐 메시지의 팝업 확인입니다.
`x-ms-time-next-visible`	메시지가 큐에 표시되는 시기를 나타내는 UTC 날짜/시간 값입니다.
`x-ms-client-request-id`	이 헤더를 사용하여 요청 및 해당 응답의 문제를 해결할 수 있습니다. 이 헤더의 값은 요청에 있는 경우 헤더의 `x-ms-client-request-id` 값과 같습니다. 값은 최대 1,024개의 ASCII 문자입니다. 헤더가 `x-ms-client-request-id` 요청에 없으면 이 헤더가 응답에 표시되지 않습니다.

응답 메시지 본문

없음.

Authorization

계정 소유자는 이 작업을 수행할 수 있습니다. 또한 이 작업을 수행할 수 있는 권한이 있는 공유 액세스 서명이 있는 모든 사용자가 이 작업을 수행할 수 있습니다.

샘플 요청 및 응답

다음 요청은 대기열 메시지의 가시성을 30초 연장하고 해당 내용을 업데이트합니다.

PUT https://myaccount.queue.core.windows.net/myqueue/messages/663d89aa-d1d9-42a2-9a6a-fcf822a97d2c?popreceipt=AgAAAAEAAAApAAAAGIw6Q29bzAE%3d&visibilitytimeout=30&timeout=30 HTTP/1.1

요청은 다음 헤더와 함께 전송됩니다.

x-ms-version: 2011-08-18  
x-ms-date: Mon, 29 Aug 2011 17:17:21 GMT  
Authorization: SharedKey myaccount:batcrWZ35InGCZeTUFWMdIQiOZPCW7UEyeGdDOg7WW4=  
Content-Length: 75

요청은 다음 XML 본문과 함께 전송됩니다.

<QueueMessage>  
    <MessageText>new-message-content</MessageText>  
</QueueMessage>

요청이 전송되면 다음 응답이 반환됩니다.

HTTP/1.1 204 No Content  
Content-Length: 0  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: df34a7dd-3cbe-4206-a586-d6de3cf225a7  
x-ms-version: 2011-08-18  
x-ms-popreceipt: AwAAAAIAAAApAAAAINtMQ29bzAEBAAAA  
x-ms-time-next-visible: Mon, 29 Aug 2011 17:17:51 GMT  
Date: Mon, 29 Aug 2011 17:17:21 GMT

비고

Update Message 지정된 메시지가 큐에 없거나 지정된 팝 확인이 메시지와 일치하지 않으면 작업이 실패합니다.

팝업 확인은 작업 또는 작업에 의해 Get Messages 반환됩니다.Update Message 팝 영수증은 다음 이벤트 중 하나가 발생할 때까지 유효합니다.

메시지가 만료되었습니다.
메시지가 수신된 마지막 팝 확인( Get Messages 또는 Update Message)을 사용하여 삭제되었습니다.
보이지 않는 시간이 경과했으며 메시지가 요청에 의해 큐에서 제거되었습니다.Get Messages 보이지 않는 시간이 경과하면 메시지가 다시 표시됩니다. 다른 Get Messages 요청에 의해 검색된 경우 반환된 팝업 확인을 사용하여 메시지를 삭제하거나 업데이트할 수 있습니다.
메시지가 새 가시성 제한 시간으로 업데이트되었습니다. 메시지가 업데이트되면 새 팝 영수증이 반환됩니다.

이 Update Message 작업을 사용하여 큐 메시지의 보이지 않음을 지속적으로 확장할 수 있습니다. 이 기능은 작업자 역할이 큐 메시지를 임대하려는 경우에 유용할 수 있습니다. 예를 들어 작업자 역할이 메시지 가져오기를 호출하고 메시지를 처리하는 데 더 많은 시간이 필요하다는 것을 인식하는 경우 메시지가 처리될 때까지 메시지의 보이지 않음을 지속적으로 확장할 수 있습니다. 처리 중에 작업자 역할이 실패하면 결국 메시지가 다시 표시되고 다른 작업자 역할이 이를 처리할 수 있습니다.

메시지는 UTF-8 인코딩을 사용하여 XML 요청에 포함할 수 있는 형식이어야 합니다. 메시지에 태그를 포함하려면 메시지의 내용이 Base64로 인코딩되어야 합니다. 인코딩되지 않은 메시지의 XML 태그는 메시지가 유효하지 않게 만듭니다. 잘못된 문자(예: 0x1F)가 메시지에 포함된 경우 XML로 이스케이프된 경우에도 메시지의 후속 읽기는 성공하지 못합니다.

메시지가 너무 크면 서비스는 상태 코드 400(잘못된 요청)을 반환합니다.

참고하십시오

Azure Storage에 대한 요청 권한 부여
상태 및 오류 코드
큐 스토리지 오류 코드

Last updated on 2025-10-22