REST 생성자 API 사용

Event Streams는 기존 시스템을 Event Streams Kafka 클러스터에 연결하는 데 도움이 되는 REST API를 제공합니다. API를 사용하여 Event Streams 를 RESTful API를 지원하는 시스템과 통합할 수 있습니다.

REST 생성자 API는 Event Streams Standard및 Enterprise 플랜의 일부로만 사용 가능합니다.

REST 생성자 API는 보안 HTTP 엔드포인트를 통해 Event Streams에 메시지를 생성하기 위한 확장 가능한 REST 인터페이스입니다. 이벤트 데이터를 Event Streams에 전송하고, Kafka 기술을 사용하여 데이터 피드를 처리하고, Event Streams 기능을 활용하여 데이터를 관리하십시오.

API를 사용하여 기존 시스템을 Event Streams에 연결하십시오. 메시지 키, 헤더 및 메시지를 작성할 토픽 지정을 포함하여 시스템에서 Event Streams로의 생성 요청을 작성하십시오.

REST 생성자 API에 액세스하기

서비스 인스턴스에 대한 서비스 인증 정보 오브젝트 또는 서비스 키에서 API에 연결하는 데 필요한 URL 및 인증 정보 세부사항을 검색해야 합니다. 이러한 오브젝트 작성에 대한 자세한 정보는 Event Streams에 연결의 내용을 참조하십시오.

API 엔드포인트의 URL은 kafka_http_url 특성에 제공됩니다.

인증

지원되는 인증 메커니즘은 베어러 토큰을 사용하는 것입니다. IBM Cloud CLI를 사용하여 토큰을 얻으려면 먼저 IBM Cloud 에 로그인한 후 다음 명령을 실행하십시오.

ibmcloud iam oauth-tokens

이 토큰을 HTTP 요청의 권한 헤더에 Bearer<token> 양식으로 두십시오. API 키 또는 JWT 토큰이 모두 지원됩니다.

REST 생성자 API를 사용하여 메시지 생성

생성자 API의 v2 엔드포인트를 사용하여 text, binary, JSON 또는 avro 유형의 메시지를 주제로 전송하십시오. v2 엔드포인트를 사용하면 avro 데이터 유형에 대한 스키마를 지정하여 Event Streams 스키마 레지스트리를 사용할 수 있습니다.

다음 코드는 curl을 사용하여 text 유형의 메시지를 전송하는 예를 보여줍니다.

curl -v -X POST \
-H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
  "headers": [
    {
      "name": "colour",
      "value": "YmxhY2s="
    }
  ],
  "key": {
    "type": "text",
    "data": "Test Key"
  },
  "value": {
    "type": "text",
    "data": "Test Value"
  }
}' \
"$kafka_http_url/v2/topics/$topic_name/records"

API에 대한 자세한 정보는 Event Streams REST Producer API 참조를 참조하십시오.

스키마를 준수하는 메시지 생성

REST 생성자 API의 v2 엔드포인트를 사용하면 메시지 키 및 값이 스키마를 준수하는 방식으로 메시지를 생성할 수 있습니다. 키 및 값에 다른 스키마를 지정할 수 있습니다. 지원되는 시리얼라이저는 confluent 이고 지원되는 데이터 유형은 avro 입니다. 스키마는 Event Streams 스키마 레지스트리에 작성되고 저장됩니다. 자세한 정보는 Event Streams 스키마 레지스트리 를 참조하십시오.

다음 스키마 이름 지정 전략이 허용됩니다.

  • 토픽 이름 지정 전략: 토픽의 이름은 스키마 아티팩트 ID를 파생시키는 데 사용됩니다. ID는 키에 대해 "<topicName>-key" 형식을 사용하고 값에 대해 "<topicName>-value" 형식을 취합니다. 여기서 topicName은(는) 토픽 이름입니다.

  • 레코드 이름 지정 전략: 스키마의 레코드 이름은 스키마 아티팩트 ID를 파생시키는 데 사용됩니다. ID는 키에 대해 "<composite-recordName>-key" 형식을 사용하고 값에 대해 "<composite-recordName>-value" 형식을 취합니다. 스키마 네임스페이스 필드가 지정되면 composite-recordName 은 "< namespace>.<recordName>" 값을 사용하고, 그렇지 않으면 "<recordName>" 값을 사용합니다.

  • TopicRecord 이름 지정 전략: 주제의 이름과 레코드의 이름 모두 스키마 아티팩트 ID를 파생하는 데 사용됩니다. ID는 키에 대해 "<topicName>-<recordName>-key" 형식을 사용하고 값에 대해 "<topicName>-<composite-recordName>-value" 형식을 사용합니다. 여기서 topicName은 토픽 이름입니다. 스키마 네임스페이스 필드가 지정되면 composite-recordName 은 "< namespace>.<recordName>" 값을 사용하고, 그렇지 않으면 "<recordName>" 값을 사용합니다.

다음 코드는 curl을 사용하여 schema 필드 아래에 지정된 스키마를 준수하는 메시지를 전송하는 예를 보여줍니다.

curl -v -X POST \
-H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
  "value": {
    "type": "avro",
    "schema": "{\"namespace\": \"com.eventstreams.samples\",\"type\": \"record\",\"name\": \"recordValueName\",\"fields\": [{\"name\": \"valueName\", \"type\": \"string\"}]}",
    "schema_name_strategy": "record",
    "data": "{\"valueName\": \"sampleValueName\"}"
  }
}' \
"$kafka_http_url/v2/topics/$topic_name/records?serializer=confluent"

기존 엔드포인트에서 REST 생성자 API의 v2 엔드포인트로 마이그레이션

API 표준과의 더 나은 사용 및 맞추기를 위해 v2 엔드포인트가 몇 가지 개선되었습니다. 이러한 개선사항을 최대한 활용하려면 기존 애플리케이션을 변경하십시오.

다음 고려사항은 마이그레이션을 계획하는 데 도움이 될 수 있습니다.

  1. REST 생성자 API에 액세스:

    기존 URL과 동일한 방법으로 v2 엔드포인트에 액세스할 수 있습니다. 이 방법은 서비스 인스턴스의 kafka_http_url 특성 값을 확보하는 것입니다. 사용할 경로는 /v2/topics/<topic_name>/records입니다.

    Example URL: https://service-instance-adsf1234asdf1234asdf1234-0000.us-south.containers.appdomain.cloud/v2/topics/topic_name/records

  2. 인증:

    지원되는 인증 메커니즘은 베어러 토큰입니다. 보안을 강화하기 위해 API키를 사용한 기본 인증이 더 이상 허용되지 않습니다.

    Example Header:  -H "Authorization: Bearer $token"

  3. Headers:

    Content-Type 및 Accept 헤더를 application/json(으)로 설정하십시오.

    Example Headers:  -H "Content-Type: application/json" -H "Accept: application/json"

  4. 페이로드:

    JSON 형식의 v2 엔드포인트에 대한 페이로드를 제공하십시오. 페이로드에서 메시지 키, 헤더 및 데이터를 정의할 수 있습니다. base64 인코딩된 값을 사용하여 목록 양식으로 헤더를 지정할 수 있습니다. 그러나 메시지 키 및 헤더는 선택사항입니다.

    Example payload:
{
  "headers": [
  {
   "name": "colour",
   "value": "YmxhY2s="
  },
  "key": {
   "type": "text",
   "data": "Test Key"
  },
  "value": {
   "type": "text",
   "data": "Test Value"
  }
 }

    키 및 값 오브젝트 아래의 필드 유형에 대해 지원되는 다음 데이터 유형 중 하나를 지정해야 합니다.

    a. 텍스트: 제공되는 데이터는 문자의 선형 시퀀스로 구성되는 일반 텍스트 형식으로 유효성 검증됩니다.

    b. 2진: 제공된 데이터가 base64-encoded 2진형식으로 유효성 검증됩니다.

    c. JSON: 제공되는 데이터는 JSON 형식으로 유효성 검증됩니다.

    d. Avro: 데이터는 Apache Avro 데이터 형식으로 유효성 검증됩니다.

  5. 오류 응답:

    오류 응답에는 trace, error message, error code, more_info 및 target 특성이 포함되어 있습니다.

    Example error response:
{
 "trace": "a222e93c-e5f9-435d-b275-5d4919ea87ed",
 "error": {
  "code": "invalid_type",
  "message": "'type' field in 'value' object is required ...",
  "more_info": "https://cloud.ibm.com/apidocs/event-streams/restproducer_v2",
  "target": {
   "type": "field",
   "name": "type"
  }
 }
}

제한사항

REST 생성자 API를 사용하는 경우, 요청 페이로드로 전달되는 메시지의 최대 크기에 제한사항이 있습니다. 페이로드의 최대 크기는 64K로 제한됩니다.

API 참조

v2 엔드포인트 API에 대한 전체 세부사항은 Event Streams REST 생성자 v2 API 참조를 참조하십시오.

기존 엔드포인트 API에 대한 전체 세부사항은 Event Streams REST 생성자 API 참조를 참조하십시오.