메시지 추가

아티클
08/05/2023

Put Message 작업은 메시지 큐의 뒤에 새 메시지를 추가합니다. 표시 시간 제한 시간이 만료될 때까지 메시지를 표시하지 않도록 표시 시간 제한도 지정할 수 있습니다. 메시지는 UTF-8 인코딩으로 XML 요청에 포함할 수 있는 형식이어야 합니다. 인코딩된 메시지는 버전 2011-08-18 이상의 경우 최대 64키비트(KiB) 또는 이전 버전의 경우 8KiB일 수 있습니다.

요청

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

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

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

에뮬레이트된 스토리지 서비스에 대해 요청하는 경우 에뮬레이터 호스트 이름 및 Queue Storage 포트를 로 127.0.0.1:10001지정한 다음 에뮬레이트된 스토리지 계정 이름을 지정합니다.

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

자세한 내용은 로컬 Azure Storage 개발에 Azurite 에뮬레이터 사용을 참조하세요.

URI 매개 변수

요청 URI에 다음 매개 변수를 지정할 수 있습니다.

매개 변수	Description
`visibilitytimeout=<int=seconds>`	선택 사항입니다. 서버 시간을 기준으로 새 표시 시간 제한 값(초)을 지정합니다. 지정된 경우 2011-08-18 이상을 사용하여 `x-ms-version` 요청을 수행해야 합니다. 지정하지 않으면 기본값은 0입니다. 새 값은 0보다 크거나 같아야 하며 7일을 초과할 수 없습니다. 메시지의 표시 시간 제한은 만료 날짜 이후의 값으로 설정할 수 없습니다. Time-to-Live 값보다 작은 값으로 설정합니다 `visibilitytimeout` .
`messagettl=<int-seconds>`	선택 사항입니다. 메시지에 대한 TTL(time-to-live) 간격(초)을 지정합니다. 2017-07-29 이전 버전에서 허용되는 최대 라이브 시간은 7일입니다. 버전 2017-07-29 이상에서는 최대 TTL(Time to Live)이 양수일 수 있으며 `-1`, 이는 메시지가 만료되지 않음을 나타냅니다. 이 매개 변수를 생략한 경우 기본 TTL(time-to-live)은 7일입니다.
`timeout`	선택 사항입니다. `timeout` 매개 변수는 초 단위로 표시됩니다. 자세한 내용은 큐 서비스 작업에 대한 시간 제한 설정을 참조하세요.

요청 헤더

필수 및 선택적 요청 헤더는 다음 표에 설명되어 있습니다.

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

요청 본문

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

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

샘플 요청

Request:  
POST https://myaccount.queue.core.windows.net/messages?visibilitytimeout=30&timeout=30 HTTP/1.1  
  
Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Tue, 30 Aug 2011 01:03:21 GMT  
Authorization: SharedKey myaccount:sr8rIheJmCd6npMSx7DfAY3L//V3uWvSXOzUBCV9wnk=  
Content-Length: 100  
  
Body:  
<QueueMessage>  
<MessageText>PHNhbXBsZT5zYW1wbGUgbWVzc2FnZTwvc2FtcGxlPg==</MessageText>  
</QueueMessage>

응답

응답에는 HTTP 상태 코드 및 응답 헤더 집합이 포함되어 있습니다.

상태 코드

작업에 성공하면 상태 코드 201(만들어짐)이 반환됩니다.

상태 코드에 대한 자세한 내용은 상태 및 오류 코드를 참조하세요.

응답 헤더

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

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

응답 본문

버전 2016-05-31을 기준으로 작업에 대한 Put Message 응답은 응답 본문에 메시지 정보를 포함합니다. 반환된 본문의 XML 형식은 여기에 설명되어 있습니다.

MessageID 요소는 큐에서 메시지를 식별하는 GUID 값입니다. 이 값은 Queue Storage에서 메시지에 할당되며 클라이언트에 불투명합니다. 이 값은 PopReceipt 요소의 값과 함께 사용하여 큐에서 메시지를 삭제하거나 업데이트할 수 있습니다. PopReceipt 값은 클라이언트에도 불투명하며 메시지 삭제 또는 메시지 업데이트 API를 사용할 때 필요합니다.

InsertionTime, ExpirationTime 및 TimeNextVisible 요소는 UTC 값으로 표현되며, RFC 1123 설명에 따라 형식이 지정됩니다.

<QueueMessagesList>
    <QueueMessage>
      <MessageId>string-message-id</MessageId>
      <InsertionTime>insertion-time</InsertionTime>
      <ExpirationTime>expiration-time</ExpirationTime>
      <PopReceipt>opaque-string-receipt-data</PopReceipt>
      <TimeNextVisible>time-next-visible</TimeNextVisible>
    </QueueMessage>
</QueueMessagesList>

샘플 응답

Response Status:
HTTP/1.1 200 OK
Response headers:
Transfer-Encoding: chunked
Content-Type: application/xml
x-ms-version: 2016-05-31
Date: Fri, 09 Oct 2016 21:04:30 GMT
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0

Response Body:

<?xml version="1.0" encoding="utf-8"?>
<QueueMessagesList>
  <QueueMessage>
    <MessageId>5974b586-0df3-4e2d-ad0c-18e3892bfca2</MessageId>
    <InsertionTime>Fri, 09 Oct 2016 21:04:30 GMT</InsertionTime>
    <ExpirationTime>Fri, 16 Oct 2016 21:04:30 GMT</ExpirationTime>
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>
    <TimeNextVisible>Fri, 09 Oct 2016 23:29:20 GMT</TimeNextVisible>
   </QueueMessage>
</QueueMessagesList>

권한 부여

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

설명

선택적 표시 시간 제한은 메시지가 보이지 않는 시간을 지정합니다. 제한 시간이 만료되면 메시지가 표시됩니다. 표시 시간 초과를 지정하지 않으면 기본값 0이 사용됩니다.

선택적 메시지 Time-to-Live는 메시지가 큐에 남아 있는 기간을 지정합니다. 메시지는 TTL(Time to Live) 기간이 만료되면 큐에서 삭제됩니다.

메시지는 UTF-8 인코딩으로 XML 요청에 포함할 수 있는 형식이어야 합니다. 메시지에 태그를 포함하려면 메시지 콘텐츠가 XML로 이스케이프되거나 Base64로 인코딩되어야 합니다. 메시지가 큐에 추가되기 전에 이스케이프되거나 인코딩되지 않은 메시지의 XML 태그가 제거됩니다.

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

추가 정보

Azure Storage에 대한 요청 권한 부여
상태 및 오류 코드
큐 서비스 오류 코드