Report 부분 편집과 이미지 읽기
미저장 초안과 참고 문맥 캡처
context = report.capture_context(reads=["input", "summary"], writes=["summary"])
# 보고서 전체를 참고했다면 reads=None을 사용합니다.sourceState="draft"인 분리된 복사본을 반환하며 자동 저장하지 않습니다. baseTarget은 기준 저장 리비전이지 이 초안 자체의 저장 증명이 아닙니다. 아직 저장하지 않은 Report면 None입니다. blocks, values에는 현재 본문과 입력의 canonical 값·타입·단위가 포함됩니다. reads에는 실제로 제공한 참고 범위를 모두 넣어야 합니다. writes는 수정할 블록 key입니다. 전체 캡처는 새 블록 추가·순서 변경도 검사합니다. 연결 변경은 보수적으로 모든 관련 캡처를 무효화합니다. 캡처는 첨부 파일 bytes를 읽지 않습니다. 미저장 첨부는 아래 attachment.capture()로 먼저 고정할 수 있습니다. 문맥은 읽기/쓰기 합계 64개 블록, 직렬화한 UTF-8 JSON 262144 bytes까지입니다. 초과하면 전체 요청을 거절하고 예외의 omitted_block_keys에 반환하지 않은 요청 블록을 제공합니다. 내용을 조용히 잘라내지 않습니다.
참고 내용까지 비교해 수정 적용
context = report.capture_context(reads=["input", "measurements"],
writes=["input", "measurements", "summary"])
candidate = {**context["blocks"]["summary"],
"content": [{"type": "text", "text": "검토한 결론"}]}
report.apply_edits({"summary": candidate}, context=context,
values={"input": {"width": {"value": 8, "unit": "mm"}}},
cells=[{"tableKey": "measurements", "rowKey": "row1", "fieldKey": "width", "value": 8}])
report.save()참고 블록·수정 대상·타입·단위 또는 기준 저장 target이 바뀌면 거절합니다. 범위 밖 독립적인 블록 편집은 허용합니다. 모든 후보 블록과 대상을 먼저 검증하므로 잘못된 두 번째 후보 때문에 첫 번째 후보만 초안에 반영되지 않습니다. Core의 저장 검증은 여전히 save()가 수행합니다. values와 cells는 기존 입력·표 전용 명령을 사용하며, 본문 교체와 함께 전부 검증한 후 로컬 초안에 반영합니다. 행 ID 변경·중복 셀 수정·본문 전체 교체와 같은 블록의 입력/표 변경이 겹치는 요청은 거절합니다. 표 셀은 기존 타입과 단위를 유지합니다. values/cells를 생략한 기존 본문 편집도 그대로 사용할 수 있습니다.
거절된 결과는 호출자가 보관해 재검토할 수 있습니다. 자동 재생성·자동 재기준 설정은 하지 않습니다. context는 권한 증명이나 영속 메모리 형식이 아닙니다. 장기 보관할 출처는 저장 후의 정확한 리비전과 파일 참조로 고정하고, 재사용할 때 현재 접근 권한을 다시 확인해야 합니다.
미저장 이미지 bytes 고정
attachment = section.attachment("figure", "/local/figure.png", media_type="image/png")
image = attachment.capture(max_bytes=8_388_608)
# image: sourceState, baseTarget, contentRef, size, mime, bytes
# 파일이 바뀌거나 없어져도 image["bytes"]와 이후 capture()는 같은 내용입니다.
report.save() # 캡처한 bytes를 업로드하고 저장합니다.캡처는 Report 저장이나 업로드를 하지 않습니다. 로컬 초안이 bytes를 소유하며 장기 보관이나 재시작 복구를 보장하는 기록은 아닙니다. 이후 저장과 재시도는 캡처된 내용을 사용합니다. 캡처하지 않은 첨부는 기존처럼 저장 시점에 원본 파일을 읽습니다. 반환한 bytes는 불변이며 dict 수정은 내부 스냅샷에 영향을 주지 않습니다. digest만 지정한 미저장 첨부는 bytes 접근 권한이 아니므로, bytes를 읽으려면 저장된 revision이 필요합니다.
입력 표 다시 열기
report.table(table_key)는 생성하거나 다시 연 Report의 등록된 입력 표를 반환합니다. 계산 결과 표는 입력 셀 편집 대상이 아닙니다.
셀 읽기
table = report.table("measurements")
before = table.cell("row1", "width")
# {"kind": "int64", "value": "4", "unit": None}행 순서 대신 문자열 또는 정수 행 ID와 field key를 사용합니다. 반환값은 분리된 복사본입니다.
셀 수정
table.set_cell("row1", "width", 10, expected=before)
report.save()같은 타입·단위를 유지합니다. 행 ID 열, 없는 행/열, expected와 달라진 셀은 거절합니다. 여러 셀의 변경을 모은 뒤 save()하면 본문과 계산 입력 데이터가 함께 검증·저장됩니다.
선택 텍스트 읽기
selection = report.block("intro").select(3, 4)
text = selection.read()범위는 Python Unicode code point 기준입니다. emoji도 해당 규칙을 따르며 결합 문자를 자동으로 확장하지 않습니다. inline 입력/결과를 포함하면 일반 텍스트로 읽거나 교체하지 못합니다.
선택 텍스트 교체
selection.replace("図")
report.save()빈 범위는 삽입, 빈 문자열 교체는 삭제입니다. 새 텍스트는 선택 첫 글자의 marks를 사용하며, 빈 범위에서는 앞 텍스트의 marks를 사용합니다. 주변 서식은 유지합니다. 선택 이후 해당 블록이 바뀌면 다시 선택해야 합니다.
블록 전체를 지연해서 수정할 때는 block.replace(candidate, expected=before)로 캡처한 초안을 확인합니다. 이 비교는 로컬 초안 보호이고 저장 revision의 CAS는 별도로 수행됩니다.
필요한 부분만 읽기
context = client.read_report("note", revision=revision,
blocks=["intro"],
tables={"measurements": {"rows": ["row1"], "fields": ["width"]}},
attachments=["figure"])revision은 정확한 sha256:... 저장 revision입니다. 결과는 target과 selection이며, selection은 blocks, tables, attachments를 포함합니다. 블록/셀은 canonical 노드로 반환해 타입·단위·결과 참조를 보존합니다. 이미지 바이트를 자동으로 포함하지 않습니다.
상한은 블록 64개, 표 16개, 표당 행 256개·열 64개, 전체 셀 4096개, 첨부 64개, selection JSON 256 KiB입니다. 없는 대상·중복·상한 초과는 거절하며 조용히 잘라내지 않습니다. SDK에 전체 Report를 전송하지 않지만 서버는 기존 저장본 전체를 읽고 검증합니다.
이미지 등 첨부 원본 읽기
section.attachment("figure", "/local/output/figure.png", media_type="image/png")
saved = client.save(report)
image_bytes = client.read_attachment(report.report_key, "figure",
revision=str(saved.revision_ref), max_bytes=8_388_608)이미지 생성 서비스의 출력 파일도 같은 attachment 경로를 사용합니다. PNG/JPEG/SVG는 기존 지원 미디어 타입입니다. 크기 상한을 확인한 뒤 revision-scoped 청크를 읽고 MIME/size/offset 및 최종 content digest를 검증합니다. 큰 파일의 디스크 내보내기는 client.export_documents를 사용합니다.
원본 바이트 읽기는 모델의 이미지 이해/OCR과 다릅니다. 이 API는 이미지 생성·분석 모델을 실행하지 않고, Report 본문에 base64·임시 URL·provider 키를 저장하지 않습니다. 현재 attachment 표시를 새 inline 이미지 편집 UI로 확장한 것도 아닙니다.