Snowpipe REST API

사용자는 REST 엔드포인트를 호출하여 파이프와 상호 작용합니다. 이 항목에서는 로드 내역 보고서를 수집하고 가져올 파일 목록을 정의하기 위해 사용할 수 있는 Snowpipe REST API에 대해 설명합니다.

Snowflake는 Snowpipe REST API 작업을 간소화하는 Java 및 Python APIs도 제공합니다.

이 항목의 내용:

데이터 파일 수집

Snowpipe API는 수집할 파일 목록을 정의하기 위해 사용할 수 있는 REST 엔드포인트를 제공합니다.

엔드포인트: insertFiles

테이블에 수집할 파일에 대해 Snowflake에 알립니다. 이 엔드포인트에서 응답이 수신되면 Snowflake가 테이블에 추가할 파일 목록을 기록했음을 의미합니다. 이는 파일이 수집되었음을 의미하지 않습니다. 자세한 내용은 아래 응답 코드를 참조하십시오.

대부분의 경우 Snowflake는 몇 분 내에 대상 테이블에 새로운 데이터를 삽입합니다.

method

POST

post url

https://{account}.snowflakecomputing.com/v1/data/pipes/{pipeName}/insertFiles?requestId={requestId}

post body

다음 특성을 갖는 JSON 오브젝트:

속성

필수

설명

account

예

Snowflake 계정의 계정 식별자 입니다.

pipeName

예

대/소문자를 구분하는 정규화된 파이프 이름입니다. 예: myDatabase.mySchema.myPipe.

requestId

아니요

시스템 전체에서 요청을 추적하기 위해 사용되는 문자열입니다. 각 요청에 임의 문자열(예: UUID)을 제공하는 것이 좋습니다.
content-type

text/plain

application/json

header fields

수락: text/plain 또는 application/json

인증: BEARER <jwt_토큰>

  • text/plain 의 경우, 내용은 라인당 1개씩 경로와 파일 이름의 목록입니다. size 매개 변수는 허용되지 않습니다.

  • application/json 의 경우 내용은 경로, 파일 이름, 파일 크기의 목록입니다(선택 사항이지만 더 나은 성능을 위해 권장됨). 예시 페이로드는 다음과 같습니다.

    {
  "files":[
    {
      "path":"filePath/file1.csv",
      "size":100
    },
    {
      "path":"filePath/file2.csv",
      "size":100
    }
  ]
}
    Copy

논리적이고 세분화된 경로를 사용하여 스테이지에서 데이터를 분할하는 방식으로 권장 모범 사례를 따르는 경우 페이로드의 경로 값에는 스테이징된 파일에 대한 전체 경로가 포함됩니다.

참고

  • 게시에는 최대 5000개의 파일이 포함될 수 있습니다.

  • UTF-8을 사용하여 직렬화하는 경우 지정된 각 파일 경로의 길이는 1024바이트 이하여야 합니다.

response body

응답 코드:

  • 200 — 성공. 수집할 파일 큐에 파일이 추가되었습니다.

  • 400 — 실패. 형식이 유효하지 않거나 제한을 초과하여 응답이 유효하지 않습니다.

  • 404 — 실패. pipeName 을 인식할 수 없습니다.

    엔드포인트를 호출할 때 사용된 역할에 충분한 권한이 없는 경우에도 이 오류 코드가 반환될 수 있습니다. 자세한 내용은 액세스 권한 부여하기 섹션을 참조하십시오.

  • 429 — 실패. 요청 빈도 제한을 초과했습니다.

  • 500 — 실패. 내부 오류가 발생했습니다.

응답 페이로드:

API 응답 성공(즉, 200 코드) 시 응답 페이로드에는 requestId 및 status 요소가 JSON 형식으로 포함됩니다. 오류가 발생하면 오류에 대한 세부 정보가 응답 페이로드에 포함될 수 있습니다.

파이프 정의의 COPY INTO <테이블> 문에 PATTERN 복사 옵션이 포함된 경우 unmatchedPatternFiles 특성에는 헤더에 제출된 파일 중 정규 식과 일치하지 않아 건너뛴 파일이 나열됩니다.

내역 보고서 로드

Snowpipe API는 로드 파일을 가져오기 위한 REST 엔드포인트를 제공합니다.

엔드포인트: insertReport

최근에 내용이 테이블에 수집된 insertFiles 를 통해 제출된 파일의 보고서를 검색합니다. 대용량 파일의 경우 이는 파일의 일부일 수 있습니다.

이 엔드포인트에 대한 다음 제한 사항을 참고하십시오.

  • 가장 최근 이벤트 10,000개가 유지됩니다.

  • 이벤트는 최대 10분 동안 유지됩니다.

insertFiles 을 통해 제출된 파일의 데이터가 테이블에 커밋되어 쿼리에 사용할 수 있는 경우 이벤트가 발생합니다. insertReport 엔드포인트는 UNIX 명령의 끝으로 간주할 수 있습니다. 이 명령을 반복적으로 호출하면 시간 경과에 따른 파이프의 전체 이벤트 내역을 확인할 수 있습니다. 이벤트가 누락되지 않도록 명령을 자주 호출해야 합니다. 빈도는 파일이 insertFiles 로 전송되는지에 따라 다릅니다.

method

GET

get url

https://<계정_식별자>.snowflakecomputing.com/v1/data/pipes/<pipeName>/insertReport?requestId=<requestId>&beginMark=<beginMark>

header fields

수락: 텍스트/일반 또는 애플리케이션/json

인증: BEARER <jwt_토큰>

get body

다음 특성을 갖는 JSON 오브젝트:

속성

필수

설명

account_identifier

예

Snowflake 계정에 대한 고유 식별자입니다.

계정 식별자의 선호 형식은 다음과 같습니다.

organization_name-account_name

Snowflake 조직 및 계정의 이름입니다. 자세한 내용은 형식 1(기본 설정): 조직의 계정 이름 섹션을 참조하십시오.

아니면, 필요한 경우 계정이 호스팅되는 리전 및 클라우드 플랫폼 과 함께 계정 로케이터 를 지정합니다. 자세한 내용은 형식 2(레거시): 리전의 계정 로케이터 섹션을 참조하십시오.

pipeName

예

대/소문자를 구분하는 정규화된 파이프 이름입니다. 예: myDatabase.mySchema.myPipe.

requestId

아니요

시스템 전체에서 요청을 추적하기 위해 사용되는 문자열입니다. 각 요청에 임의 문자열(예: UUID)을 제공하는 것이 좋습니다.

beginMark

예

insertReport 에 대하여 이전 호출에서 반환된 마커로, insertReport 를 반복적으로 호출할 때 표시되는 반복 이벤트의 수를 줄이기 위한 용도로 사용할 수 있습니다. 이는 참고 사항이며, 이러한 경우에도 반복 이벤트를 반환할 수 있습니다.
response body

응답 코드:

  • 200 — 성공. 반환되는 보고서입니다.

  • 400 — 실패. 형식이 유효하지 않거나 제한을 초과하여 응답이 유효하지 않습니다.

  • 404 — 실패. pipeName 을 인식할 수 없습니다.

    엔드포인트를 호출할 때 사용된 역할에 충분한 권한이 없는 경우에도 이 오류 코드가 반환될 수 있습니다. 자세한 내용은 액세스 권한 부여하기 섹션을 참조하십시오.

  • 429 — 실패. 요청 빈도 제한을 초과했습니다.

  • 500 — 실패. 내부 오류가 발생했습니다.

응답 페이로드:

성공 응답(200)에는 최근에 테이블에 추가된 파일에 대한 정보가 포함됩니다. 이 보고서는 대용량 파일의 일부만 나타낼 수 있음에 유의하십시오.

예:

{
  "pipe": "TESTDB.TESTSCHEMA.pipe2",
  "completeResult": true,
  "nextBeginMark": "1_39",
  "files": [
    {
      "path": "data2859002086815673867.csv",
      "stageLocation": "s3://mybucket/",
      "fileSize": 57,
      "timeReceived": "2017-06-21T04:47:41.453Z",
      "lastInsertTime": "2017-06-21T04:48:28.575Z",
      "rowsInserted": 1,
      "rowsParsed": 1,
      "errorsSeen": 0,
      "errorLimit": 1,
      "complete": true,
      "status": "LOADED"
    }
  ]
}
Copy

응답 필드:

필드

타입

설명

pipe

문자열

파이프의 정규화된 이름입니다.

completeResult

부울

제공된 beginMark 와 치 보고서 내역의 첫 번째 이벤트 사이에서 이벤트가 누락된 경우 false 입니다. 그렇지 않으면, true 입니다.

nextBeginMark

문자열

중복 레코드가 표시되는 것을 방지하기 위해 다음 요청에서 사용할 beginMark 입니다. 이 값은 참고 사항이라는 점에 유의하십시오. 이러한 경우에도 종종 중복이 발생할 수 있습니다.

files

배열

JSON 오브젝트의 배열로, 내역 응답의 일부인 각 파일은 1개의 오브젝트를 구성합니다.
path

문자열

스테이지 위치에 상대적인 파일 경로입니다.
stageLocation

문자열

파이프에 정의된 스테이지 ID(내부 스테이지) 또는 S3 버킷(외부 스테이지) 중 하나입니다.
fileSize

long

파일 크기(바이트)입니다.
timeReceived

문자열

처리를 위해 이 파일이 수신된 시간입니다. 형식은 UTC 타임존의 ISO-8601입니다.
lastInsertTime

문자열

이 파일의 데이터가 마지막으로 테이블에 삽입된 시간입니다. 형식은 UTC 타임존의 ISO-8601입니다.
rowsInserted

long

파일에서 대상 테이블에 삽입된 행 수입니다.
rowsParsed

long

파일에서 구문이 분석된 행의 수입니다. 오류가 발생한 행은 건너뛸 수 있습니다.
errorsSeen

정수

파일에서 발생한 오류의 수입니다.
errorLimit

정수

실패한 것으로 간주되기 전에 파일에 허용된 오류의 수입니다(ON_ERROR 복사 옵션 기준).
firstError [1]

문자열

이 파일에서 발생한 첫 번째 오류에 대한 오류 메시지입니다.
firstErrorLineNum [1]

long

첫 번째 오류의 줄 번호입니다.
firstErrorCharacterPos [1]

long

첫 번째 오류의 문자 위치입니다.
firstErrorColumnName [1]

문자열

첫 번째 오류가 발생한 열의 이름입니다.
systemError [1]

문자열

파일을 처리하지 못한 이유를 설명하는 일반 오류입니다.
complete

부울

파일의 처리 여부를 나타냅니다.
status

문자열

파일의 오류 상태:

  • LOAD_IN_PROGRESS: 파일의 일부가 테이블에 로드되었지만 로드 프로세스가 아직 완료되지 않았습니다.

  • LOADED: 전체 파일이 테이블에 로드되었습니다.

  • LOAD_FAILED: 파일을 로드하지 못했습니다.

  • PARTIALLY_LOADED: 이 파일의 일부 행이 로드되었지만 다른 행은 오류로 인해 로드되지 않았습니다. 이 파일의 처리가 완료되었습니다.

[1] 이러한 필드에 대한 값은 파일에서 오류가 발생한 경우에만 제공됩니다.

엔드포인트: loadHistoryScan

내용이 테이블에 추가된 수집 파일에 대한 보고서를 가져옵니다. 대용량 파일의 경우 이는 파일의 일부일 수 있습니다. 이 엔드포인트는 두 시점 간의 내역을 살펴본다는 점에서 insertReport 와 다릅니다. 최대 10,000개의 항목이 반환되지만, 여러 번 호출하여 원하는 시간 범위를 포함할 수 있습니다.

중요

이 엔드포인트에서는 과도한 호출을 방지하기 위해 빈도가 제한됩니다. 빈도 제한(오류 코드 429)이 초과되는 것을 방지하기 위해 loadHistoryScan 이 아닌 insertReport 를 사용하는 것이 좋습니다. loadHistoryScan 을 호출할 때 데이터 로드 세트를 포함하는 가장 좁은 시간 범위를 지정합니다. 예를 들어, 8분마다 내역의 최근 10분을 읽는 것이 효과적입니다. 1분마다 최근 24시간 내역 읽기를 시도하면 빈도 제한에 도달했음을 나타내는 429 오류가 발생합니다. 빈도 제한은 각 내역 레코드를 몇 번만 읽을 수 있도록 설계되었습니다.

이러한 제한이 적용되지 않고 보다 포괄적인 뷰를 살펴볼 수 있도록, Snowflake는 파이프 또는 테이블의 로드 내역을 반환하는 Information Schema 테이블 함수인 COPY_HISTORY 를 제공합니다.

method

GET

get url

https://{account}.snowflakecomputing.com/v1/data/pipes/{pipeName}/loadHistoryScan?startTimeInclusive=<startTime>&endTimeExclusive=<endTime>&requestId=<requestId>

header fields

수락: 텍스트/일반 또는 애플리케이션/json

인증: BEARER <jwt_토큰>

get body

다음 특성을 갖는 JSON 오브젝트:

속성

필수

설명

account

예

Snowflake 계정의 계정 식별자 입니다.

pipeName

예

대/소문자를 구분하는 정규화된 파이프 이름입니다. 예: myDatabase.mySchema.myPipe.

startTimeInclusive

예

ISO-8601 형식의 타임스탬프입니다. 로드 내역 데이터를 검색하기 위한 시간 범위의 시작입니다.

endTimeExclusive

아니요

ISO-8601 형식의 타임스탬프입니다. 로드 내역 데이터를 검색하기 위한 시간 범위의 종료입니다. 생략된 경우 CURRENT_TIMESTAMP()가 범위의 종료로 사용됩니다.

requestId

아니요

시스템 전체에서 요청을 추적하기 위해 사용되는 문자열입니다. 각 요청에 임의 문자열(예: UUID)을 제공하는 것이 좋습니다.
response body

응답 코드:

  • 200 — 성공. 로드 내역 스캔 결과가 반환됩니다.

  • 400 — 실패. 형식이 유효하지 않거나 제한을 초과하여 응답이 유효하지 않습니다.

  • 404 — 실패. pipeName 을 인식할 수 없습니다.

  • 429 — 실패. 요청 빈도 제한을 초과했습니다.

  • 500 — 실패. 내부 오류가 발생했습니다.

응답 페이로드:

성공 응답(200)에는 최근에 테이블에 추가된 파일에 대한 정보가 포함됩니다. 이 보고서는 대용량 파일의 일부만 나타낼 수 있음에 유의하십시오.

예:

{
  "pipe": "TESTDB.TESTSCHEMA.pipe2",
  "completeResult": true,
  "startTimeInclusive": "2017-08-25T18:42:31.081Z",
  "endTimeExclusive":"2017-08-25T22:43:45.552Z",
  "rangeStartTime":"2017-08-25T22:43:45.383Z",
  "rangeEndTime":"2017-08-25T22:43:45.383Z",
  "files": [
    {
      "path": "data2859002086815673867.csv",
      "stageLocation": "s3://mystage/",
      "fileSize": 57,
      "timeReceived": "2017-08-25T22:43:45.383Z",
      "lastInsertTime": "2017-08-25T22:43:45.383Z",
      "rowsInserted": 1,
      "rowsParsed": 1,
      "errorsSeen": 0,
      "errorLimit": 1,
      "complete": true,
      "status": "LOADED"
    }
  ]
}
Copy

응답 필드:

필드

타입

설명

pipe

문자열

파이프의 정규화된 이름입니다.

completeResult

부울

보고서가 불완전한 경우(즉, 지정된 시간 범위의 항목 수가 10,000개의 항목 제한을 초과하는 경우) false 입니다. false 인 경우 사용자는 현재 rangeEndTime 값을 다음 항목 세트를 진행하기 위한 다음 요청의 startTimeInclusive 값으로 지정할 수 있습니다.

startTimeInclusive

문자열

요청에서 제공된 시작 타임스탬프(ISO-8601 형식)입니다.

endTimeExclusive

문자열

요청에서 제공된 종료 타임스탬프(ISO-8601 형식)입니다.

rangeStartTime

문자열

요청에 포함된 파일에서 가장 오래된 항목의 타임스탬프(ISO-8601 형식)입니다.

rangeEndTime

문자열

요청에 포함된 파일에서 가장 최근 항목의 타임스탬프(ISO-8601 형식)입니다.

files

배열

JSON 오브젝트의 배열로, 내역 응답의 일부인 각 파일은 1개의 오브젝트를 구성합니다. 배열 내에서 응답 필드는 insertReport 응답에서 반환된 필드와 동일합니다.
언어: 한국어