Snowpipe Streaming API REST 엔드포인트¶

참고

snowpipe-streaming SDK를 주요 선택 항목 및 기본 선택 항목으로 사용하는 것이 좋습니다. REST API는 처리량이 많은 시나리오에 최적화되어 있지 않습니다.

다음 요청 헤더는 Snowpipe Streaming REST API 의 모든 엔드포인트에 적용됩니다.

헤더	설명
`Authorization`	인증 토큰
`X-Snowflake-Authorization-Token-Type` (선택 사항)	JWT/OAuth

참고

단일 요청 페이로드에 허용되는 최대 크기는 16MB입니다. 데이터가 더 큰 경우 여러 요청으로 분할해야 합니다.

호스트 이름 가져오기¶

Get Hostname 은 Snowpipe Streaming REST API 와 상호 작용하는 데 사용되는 호스트 이름을 반환합니다. 각 계정에는 고유한 호스트 이름이 있습니다.

GET /v2/streaming/hostname

응답:

필드	타입	설명
호스트 이름	문자열	계정의 호스트 이름입니다.

Exchange 범위 지정 토큰¶

:code:`Exchange Scoped Token`은 Snowpipe Streaming API 관련 서비스에만 액세스하는 데 사용할 수 있는 보안 토큰을 반환합니다. 이를 통해 고객에게 보안 보호 기능을 제공합니다.

POST /oauth/token

요청:

속성	필수	구성 요소	설명
content_type	예	헤더	“application/x-www-form-urlencoded”
grant_type	예	페이로드	“urn:ietf:params:oauth:grant-type:jwt-bearer”
범위	예	페이로드	계정의 호스트 이름

응답:

필드	타입	설명
토큰	문자열	범위 지정 토큰입니다.

Open Channel¶

Open Channel 작업은 파이프 또는 테이블에 대해 새 채널을 만들거나 엽니다. 채널이 이미 존재하는 경우, Snowflake는 채널의 클라이언트 시퀀서를 범프하고 마지막으로 커밋된 오프셋 토큰을 반환합니다.

PUT /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

요청:

속성	필수	구성 요소	설명
databaseName	예	URI	데이터베이스 이름, 대/소문자 구분 안 함
schemaName	예	URI	스키마 이름, 대/소문자 구분 안 함
pipeName	예	URI	파이프 이름, 대/소문자 구분 안 함
channelName	예	URI	생성하거나 다시 여는 채널의 이름(대/소문자 구분 안 함)
offset_token	아니요	페이로드	채널을 열 때 오프셋 토큰을 설정하는 데 사용되는 문자열입니다.
requestId	아니요	쿼리 매개 변수	시스템을 통해 요청을 추적하는 데 사용되는 UUID

응답:

필드	타입	설명
next_continuation_token	String	후속 행 추가 요청에서 사용해야 하는 API 관리 토큰입니다. 토큰은 일련의 호출을 연결하여 연속적인 데이터 스트림을 순서대로 보장하고 정확히 한 번 전달하기 위해 세션 상태를 유지합니다.
channel_status	오브젝트	채널에 대한 다음과 같은 세부 정보가 포함된 중첩된 오브젝트입니다. database_name(String): 파이프가 있는 데이터베이스의 이름입니다. schema_name(String): 파이프가 있는 스키마의 이름입니다. pipe_name(String): 사용 중인 특정 파이프의 이름입니다. channel_name(String): 스트리밍 채널의 이름입니다. channel_status_code(String): 채널의 현재 상태를 나타내는 코드입니다. 예: ‘ACTIVE’. last_committed_offset_token(String): 마지막으로 커밋된 오프셋을 나타내는 토큰입니다. created_on_ms(Long): 채널이 생성된 타임스탬프(밀리초)입니다. rows_inserted(Int): 성공적으로 삽입된 총 행 수입니다. rows_parsed(Int): 구문 분석된 총 행 수입니다. rows_error_count(Int): 오류가 발생한 총 행 수입니다. last_error_offset_upper_bound(String): 마지막 오류가 발생한 오프셋의 상한을 나타내는 토큰입니다. last_error_message(string): 마지막으로 발생한 오류의 메시지입니다. last_error_timestamp(긴): 마지막 오류의 타임스탬프(밀리초)입니다. snowflake_avg_processing_latency_ms(Int): Snowflake의 평균 처리 대기 시간(밀리초)입니다.

필드

타입

설명

next_continuation_token

String

후속 행 추가 요청에서 사용해야 하는 API 관리 토큰입니다. 토큰은 일련의 호출을 연결하여 연속적인 데이터 스트림을 순서대로 보장하고 정확히 한 번 전달하기 위해 세션 상태를 유지합니다.

channel_status

오브젝트

채널에 대한 다음과 같은 세부 정보가 포함된 중첩된 오브젝트입니다.

database_name(String): 파이프가 있는 데이터베이스의 이름입니다.
schema_name(String): 파이프가 있는 스키마의 이름입니다.
pipe_name(String): 사용 중인 특정 파이프의 이름입니다.
channel_name(String): 스트리밍 채널의 이름입니다.
channel_status_code(String): 채널의 현재 상태를 나타내는 코드입니다. 예: ‘ACTIVE’.
last_committed_offset_token(String): 마지막으로 커밋된 오프셋을 나타내는 토큰입니다.
created_on_ms(Long): 채널이 생성된 타임스탬프(밀리초)입니다.
rows_inserted(Int): 성공적으로 삽입된 총 행 수입니다.
rows_parsed(Int): 구문 분석된 총 행 수입니다.
rows_error_count(Int): 오류가 발생한 총 행 수입니다.
last_error_offset_upper_bound(String): 마지막 오류가 발생한 오프셋의 상한을 나타내는 토큰입니다.
last_error_message(string): 마지막으로 발생한 오류의 메시지입니다.
last_error_timestamp(긴): 마지막 오류의 타임스탬프(밀리초)입니다.
snowflake_avg_processing_latency_ms(Int): Snowflake의 평균 처리 대기 시간(밀리초)입니다.

행 추가¶

Append Rows 작업은 지정된 채널에 행 배치를 삽입합니다.

POST /v2/streaming/data/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}/rows

요청:

속성	필수	구성 요소	설명
databaseName	예	URI	데이터베이스 이름, 대/소문자 구분 안 함
schemaName	예	URI	스키마 이름, 대/소문자 구분 안 함
pipeName	예	URI	파이프, 대/소문자 구분 안 함
channelName	예	URI	채널 이름, 대/소문자 구분 안 함
연속 토큰	예	쿼리 매개 변수	Snowflake의 연속 토큰, 클라이언트와 행 시퀀스를 모두 캡슐화합니다
offsetToken	아니요	쿼리 매개 변수	배치별 오프셋 토큰을 설정하는 데 사용되는 문자열입니다.
rows	예	페이로드	NDJSON 형식으로 수집할 실제 데이터 페이로드입니다.
requestId	아니요	쿼리 매개 변수	시스템을 통해 요청을 추적하는 데 사용되는 UUID.

참고

NDJSON 페이로드 내의 JSON 텍스트는 RFC 8259 표준을 엄격히 준수해야 합니다. 각 JSON 텍스트 다음에는 줄 바꿈 문자 \n`(:code:`0x0A)이 와야 합니다. 줄바꿈 문자 앞에 캐리지 리턴 \r`(:code:`0x0D)을 삽입할 수도 있습니다.

응답:

필드	타입	설명
next_continuation_token	문자열	클라이언트와 행 시퀀스를 모두 캡슐화하는 Snowflake의 다음 연속 토큰입니다. 다음 배치를 삽입하는 데 사용해야 합니다.

채널 제거¶

Drop Channel 작업은 메타데이터와 함께 서버 측에 채널을 드롭합니다.

DELETE /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

요청:

속성	필수	구성 요소	설명
databaseName	예	URI	데이터베이스 이름, 대/소문자 구분 안 함
schemaName	예	URI	스키마 이름, 대/소문자 구분 안 함
pipeOrTableName	예	URI	파이프 또는 테이블 이름, 대/소문자 구분 안 함
channelName	예	URI	채널 이름, 대/소문자 구분 안 함
requestId	아니요	쿼리 매개 변수	시스템을 통해 요청을 추적하는 데 사용되는 UUID

응답:

이 작업은 HTTP 상태 코드 이외의 특정 성공 응답이 없는 페이로드를 반환합니다.

채널 상태 일괄 가져오기¶

Bulk Get Channel Status 작업은 특정 클라이언트 시퀀서에 대한 채널의 상태를 반환합니다.

POST /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}:bulk-channel-status

요청:

속성	필수	구성 요소	설명
databaseName	예	URI	데이터베이스 이름, 대/소문자 구분 안 함
schemaName	예	URI	스키마 이름, 대/소문자 구분 안 함
pipeName	예	URI	파이프 이름, 대/소문자 구분 안 함
channel_names	예	페이로드	고객이 상태를 확인하려는 채널 이름 문자열 배열입니다. 이름은 대소문자를 구분합니다. 예: `{"channel_names":["channel1", "channel2"]}`.

응답:

{
  "channel_statuses": {
    "channel1": {
      "channel_status_code": "String",
      "last_committed_offset_token": "String",
      "database_name": "String",
      "schema_name": "String",
      "pipe_name": "String",
      "channel_name": "String",
      "rows_inserted": "int",
      "rows_parsed": "int",
      "rows_errors": "int",
      "last_error_offset_upper_bound": "String",
      "last_error_message": "String",
      "last_error_timestamp": "timestamp_utc",
      "snowflake_avg_processing_latency_ms": "int"
    },
    "channel2": {
      "comment": "same structure as channel1"
    }
    "comment": "potentially other channels"
  }
}

Copy

참고

서비스에서 요청된 채널을 찾을 수 없는 경우 응답 페이로드에는 channel_statuses 오브젝트 내에 해당 채널에 대한 항목이 없습니다.

각 채널에 대한 channel_statuses 필드의 설명입니다.

필드	타입	설명
channel_status_code	String	채널의 상태를 나타냅니다.
last_committed_offset_token	String	최근 커밋된 오프셋 토큰
데이터베이스_이름	String	채널이 속한 데이터베이스의 이름입니다.
스키마_이름	String	채널이 속한 스키마의 이름입니다.
파이프_이름	String	채널이 속한 파이프의 이름입니다.
channel_name	String	채널의 이름입니다.
rows_inserted	int	이 채널에 삽입된 모든 행의 개수입니다.
rows_parsed	int	구문 분석되었지만 반드시 이 채널에 삽입되지는 않은 모든 행의 개수입니다.
rows_errors	int	이 채널에 삽입할 때 오류가 발생하여 거부된 모든 행의 개수입니다.
last_error_offset_upper_bound	String	삽입된 행 세트의 마지막 오류에 해당하는 최신 오프셋 토큰의 상한값입니다. 마지막 오류가 있는 행으로 설정된 행의 실제 오프셋 토큰은 이 토큰이거나 채널 수집 순서에서 엄밀히 말하면 그 바로 앞의 토큰입니다.
last_error_message	String	해당 채널의 최신 오류 코드에 해당하는 사람이 읽을 수 있는 메시지로, 민감한 고객 데이터가 삭제되어 있습니다.
last_error_timestamp	timestamp_utc	마지막 오류가 발생한 타임스탬프입니다.
Snowflake_avg_processing_latency_ms	int	이 채널의 평균 e2e 처리 시간입니다.

오류 응답 구조¶

모든 APIs의 오류 응답에 대해 다음 JSON 페이로드 모양이 표시되어야 합니다.

{
   "error_code": "",
   "message": ""
}

Copy