Snowpipe REST API¶

엔드포인트: 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 특성에는 헤더에 제출된 파일 중 정규 식과 일치하지 않아 건너뛴 파일이 나열됩니다.

엔드포인트: 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개의 항목이 반환되지만, 여러 번 호출하여 원하는 시간 범위를 포함할 수 있습니다.

이러한 제한이 적용되지 않고 보다 포괄적인 뷰를 살펴볼 수 있도록, 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 응답에서 반환된 필드와 동일합니다.