REST 클라이언트

REST 클라이언트 (REST client)

Pulsar는 클러스터의 리소스를 관리하는 REST 엔드포인트를 제공할 뿐만 아니라, 그 리소스들의 상태를 조회하는 메서드도 제공해요. 이 문서는 HTTP로 메시지를 생산(produce)하는 엔드포인트를 다뤄요. 클라이언트 라이브러리 없이 HTTP로 Pulsar와 상호작용할 수 있어 간편하답니다.

출처: 문서

본문

Pulsar는 Pulsar 클러스터의 리소스를 관리하는 REST 엔드포인트를 제공할 뿐만 아니라, 해당 리소스의 상태를 조회하는 메서드도 제공해요. 또한 Pulsar REST는 클라이언트 라이브러리를 사용하지 않고 Pulsar와 상호작용하는 간단한 방법을 제공해요. 애플리케이션이 HTTP로 Pulsar와 상호작용하기에 편리하죠.

이 페이지는 HTTP로 메시지를 생산하기 위한 엔드포인트를 다뤄요. Pulsar 인스턴스(클러스터, 테넌트, 네임스페이스, 토픽, 스키마, 함수, 커넥터 등)를 관리하는 엔드포인트는 관리 REST API이고, REST API 및 OpenAPI 규격에 설명돼 있어요. Pulsar 5.0부터 OpenAPI 3 규격이 함께 제공되어 다른 언어용 클라이언트를 생성할 수 있어요. 아래의 생산 엔드포인트는 브로커가 같은 웹 서비스 포트에서 서비스하지만, 관리 API가 아니라 데이터 경로이며 그 규격에는 포함되지 않아요.

연결 (Connection)

Pulsar에 연결하려면 URL을 지정해야 해요.

• 비파티셔닝 또는 파티셔닝된 토픽에 메시지 생산: brokerUrl:{8080/8081}/topics/{persistent/non-persistent}/{my-tenant}/{my-namespace}/{my-topic}
• 파티셔닝된 토픽의 특정 파티션에 메시지 생산: brokerUrl:{8080/8081}/topics/{persistent/non-persistent}/{my-tenant}/{my-namespace}/{my-topic}/partitions/{partition-number}

프로듀서 (Producer)

현재 cURL이나 Postman 같은 도구로 REST를 통해 다음 대상에 메시지를 생산할 수 있어요.

• 비파티셔닝 또는 파티셔닝된 토픽
• 파티셔닝된 토픽의 특정 파티션

REST로는 Pulsar에 이미 존재하는 토픽에만 메시지를 생산할 수 있어요.

REST를 통한 메시지 소비와 읽기는 향후 지원될 예정이에요.

메시지 (Message)

요청 페이로드의 구조는 다음과 같아요.

메시지의 구조는 다음과 같아요.

스키마 (Schema)

• 현재 Primitive, Avro, JSON, KeyValue 스키마가 지원돼요.
• Primitive, Avro, JSON 스키마의 경우 문자열로 인코딩된 전체 스키마로 제공해야 해요.
• 스키마를 설정하지 않으면 메시지가 문자열 스키마로 인코딩돼요.

예시 (Example)

다음은 REST를 통해 JSON 스키마로 토픽에 메시지를 보내는 예시예요.

다음 클래스를 나타내는 메시지를 보낸다고 가정해요.

   class Seller {
        public String state;
        public String street;
        public long zipCode;
    }

    class PC {
        public String brand;
        public String model;
        public int year;
        public GPU gpu;
        public Seller seller;
    }

JSON 스키마로 토픽에 메시지를 보내려면 아래 명령을 사용해요.

curl --location --request POST 'brokerUrl:{8080/8081}/topics/{persistent/non-persistent}/{my-tenant}/{my-namespace}/{my-topic}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "valueSchema": "{\"name\":\"\",\"schema\":\"eyJ0eX...1dfQ==\",\"type\":\"JSON\",\"properties\":{\"__jsr310ConversionEnabled\":\"false\",\"__alwaysAllowNull\":\"true\"},\"schemaDefinition\":\"{\\\"type\\\":\\\"record\\\",\\\"name\\\":\\\"PC\\\",\\\"namespace\\\":\\\"org.apache.pulsar.broker.admin.TopicsTest\\\",\\\"fields\\\":[{\\\"name\\\":\\\"brand\\\",\\\"type\\\":[\\\"null\\\",\\\"string\\\"],\\\"default\\\":null},{\\\"name\\\":\\\"gpu\\\",\\\"type\\\":[\\\"null\\\",{\\\"type\\\":\\\"enum\\\",\\\"name\\\":\\\"GPU\\\",\\\"symbols\\\":[\\\"AMD\\\",\\\"NVIDIA\\\"]}],\\\"default\\\":null},{\\\"name\\\":\\\"model\\\",\\\"type\\\":[\\\"null\\\",\\\"string\\\"],\\\"default\\\":null},{\\\"name\\\":\\\"seller\\\",\\\"type\\\":[\\\"null\\\",{\\\"type\\\":\\\"record\\\",\\\"name\\\":\\\"Seller\\\",\\\"fields\\\":[{\\\"name\\\":\\\"state\\\",\\\"type\\\":[\\\"null\\\",\\\"string\\\"],\\\"default\\\":null},{\\\"name\\\":\\\"street\\\",\\\"type\\\":[\\\"null\\\",\\\"string\\\"],\\\"default\\\":null},{\\\"name\\\":\\\"zipCode\\\",\\\"type\\\":\\\"long\\\"}]}],\\\"default\\\":null},{\\\"name\\\":\\\"year\\\",\\\"type\\\":\\\"int\\\"}]}\"},

// Schema data is just the base 64 encoded schemaDefinition.

  "producerName": "rest-producer",
  "messages": [
    {
      "key":"my-key",
      "payload":"{\"brand\":\"dell\",\"model\":\"alienware\",\"year\":2021,\"gpu\":\"AMD\",\"seller\":{\"state\":\"WA\",\"street\":\"main street\",\"zipCode\":98004}}",
      "eventTime":1603045262772,
      "sequenceId":1
    },
    {
      "key":"my-key",
      "payload":"{\"brand\":\"asus\",\"model\":\"rog\",\"year\":2020,\"gpu\":\"NVIDIA\",\"seller\":{\"state\":\"CA\",\"street\":\"back street\",\"zipCode\":90232}}",
      "eventTime":1603045262772,
      "sequenceId":2
    }
  ]
}
`
// Sample message

더 알아보기 (Learn more)

• REST API 개요 — 관리 REST API를 살펴봐요.
• 프로듀서 사용하기 — 다른 클라이언트로 메시지를 게시하는 방법을 알아봐요.
• 클라이언트 라이브러리 — 다양한 언어 클라이언트를 살펴봐요.
• 스키마 — 스키마를 정의하고 쓰는 방법을 알아봐요.