참고: Python 2.7은 2024년 1월 31일 지원 종료됩니다. 기존 Python 2.7 애플리케이션을 계속 실행하고 트래픽을 받을 수 있습니다. 그러나 지원 종료 날짜 이후에는 해당 런타임을 사용하는 애플리케이션의 재배포를 App Engine에서 차단할 수 있습니다. 지원되는 최신 Python 버전으로 마이그레이션하는 것이 좋습니다.

NDB 함수

함수

ndb.add_flow_exception(exc)

예외가 로깅되지 않아야 하지만 정상적인 프로그램 흐름의 일부임을 지정합니다. (일반적으로 예외가 발생하면 애플리케이션 로그에 경고 메시지가 작성됩니다.)

인수

exc

로깅하지 않아야 하는 예외 클래스입니다.

기본적으로 다음 예외가 로깅되지 않습니다.

webob.exc.HTTPException(및 해당 하위 클래스)
ndb.Rollback

ndb.delete_multi(keys, **ctx_options)

전달된 키 시퀀스로 식별되는 항목을 삭제합니다.

인수

keys: 키 시퀀스
**ctx_options: 컨텍스트 옵션

ndb.delete_multi_async(keys, **ctx_options)

전달된 키 시퀀스로 식별되는 항목을 비동기로 삭제합니다.

인수

keys: 키 시퀀스
**ctx_options: 컨텍스트 옵션

ndb.get_multi(keys, **ctx_options)

전달된 키 시퀀스로 식별되는 항목을 가져옵니다.

인수

keys: 키 시퀀스
**ctx_options: 컨텍스트 옵션

ndb.get_multi_async(keys, **ctx_options)

전달된 키 시퀀스로 식별되는 항목을 비동기로 가져옵니다.

인수

keys: 키 시퀀스
**ctx_options: 컨텍스트 옵션

ndb.in_transaction()

현재 트랜잭션이 활성화됐는지 여부를 나타내는 부울을 반환합니다.

@ndb.non_transactional @ndb.non_transactional(allow_existing=True)

함수가 트랜잭션 밖에서 실행되도록 보장하는 데코레이터입니다.

인수:

allow_existing: True인 경우(기본값) 그리고 데코레이션된 함수가 트랜잭션의 코드에 의해 호출되는 경우, 트랜잭션과 독립적으로 함수가 실행됩니다. False인 경우 그리고 데코레이션된 함수가 트랜잭션의 코드에 의해 호출되는 경우, 예외가 발생합니다.

ndb.put_multi(entities, **ctx_options)

모델 인스턴스의 시퀀스를 저장합니다.

인수

항목: 모델 인스턴스 시퀀스
**ctx_options: 컨텍스트 옵션

ndb.put_multi_async(entities, **ctx_options)

모델 인스턴스 시퀀스를 비동기로 저장합니다.

인수

항목: 모델 인스턴스 시퀀스
**ctx_options: 컨텍스트 옵션

ndb.transaction(callback, **ctx_options)

트랜잭션에서 콜백을 실행합니다.

인수

콜백: 호출할 함수 또는 tasklet
**ctx_options: 트랜잭션 옵션

ndb.transaction_async(callback, **ctx_options)

트랜잭션에서 콜백을 비동기로 실행합니다.

인수

콜백: 호출할 함수 또는 tasklet
**ctx_options: 트랜잭션 옵션

Future를 반환합니다. Future는 콜백 결과를 반환하거나 콜백으로 인해 발생한 내용 또는 트랜잭션에 실패하는 경우 TransactionFailedError를 발생시킵니다.

인수를 콜백 함수로 전달하려면 람다를 사용합니다. 예를 들면 다음과 같습니다.

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

@ndb.transactional
@ndb.transactional(**ctx_options)

함수가 트랜잭션에서 자동으로 실행되도록 하는 데코레이터입니다.

인수:

이 데코레이터에는 트랜잭션 옵션이 있을 수 있습니다.

컨텍스트 옵션, 트랜잭션 옵션

컨텍스트 옵션을 사용하면 특정한 Datastore 작업을 다른 구성으로 실행할 수 있습니다. 예를 들어 개별 요청에 대한 읽기 정책이나 RPC 기한을 변경해야 할 수 있습니다. 이를 위해 컨텍스트 옵션을 거의 모든 작업에 전달할 수 있습니다. 일부 트랜잭션 관련 함수는 컨텍스트 옵션 집합 외에 추가적인 옵션을 포함하는 트랜잭션 옵션을 사용합니다.

다음은 컨텍스트 옵션 사용을 보여 주는 몇 가지 예입니다. 항목을 읽을 때 다음 명령어를 사용하여 RPC 기한을 1초로 설정할 수 있습니다.

key.get(deadline=1)

항목을 작성할 때 다음 명령어를 사용하여 Memcache 제한 시간을 30초로 설정할 수 있습니다.

ent.put(ndb_memcache_timeout=30)

다음 명령어를 사용하여 캐시된 항목을 삭제하고 강제로 다시 로드할 수 있습니다.

key.delete(use_datastore=False)

특수 키워드 인수 options와 config(기록상의 이유로 동일한 의미를 가짐)를 사용하면 여러 옵션을 구성 객체 1개로 지정할 수 있습니다. ndb.ContextOptions 객체이거나 (거래 함수 및 데코레이터의 경우) ndb.TransactionOptions 객체일 수 있습니다. 예를 들어 key.get(options=ndb.ContextOptions(use_cache=True))는 key.get(use_cache=True)와 동일합니다. 이러한 옵션 객체에서 설정된 옵션은 키워드 매개변수에 의해 재정의될 수 있습니다.

다음 컨텍스트 옵션을 사용할 수 있습니다.

옵션	유형	설명
`deadline`	`float`	Datastore API 호출 기한으로, 초 단위 시간으로 지정됩니다. (기본적으로 호출은 요청 핸들러 기한에 의해서만 중단됩니다.)
`read_policy`	`ndb.EVENTUAL_CONSISTENCY`	Datastore가 반환된 모든 결과에 변경사항을 적용하기를 기다리는 대신 현재 결과가 아닌 결과를 더 빨리 가져오려면 이를 `ndb.EVENTUAL_CONSISTENCY`로 설정합니다.
`force_writes`	`bool`	앱이 읽기 전용인 경우라도 쓰기 요청이 성공해야 하는지 여부를 지정합니다. (이는 사용자가 제어하는 읽기 전용 기간에만 적용됩니다.)
`use_cache`	`bool`	항목을 프로세스 내 캐시에 저장할지 여부를 지정합니다. 이 작업에 대한 프로세스 내 캐시 정책을 재정의합니다.
`use_memcache`	`bool`	항목을 Memcache에 저장할지 여부를 지정합니다. 이 작업에 대한 Memcache 정책을 재정의합니다.
`use_datastore`	`bool`	항목을 Datastore에 저장할지 여부를 지정합니다. 이 작업에 대한 Datastore 정책을 재정의합니다.
`memcache_timeout`	`int`	Memcache에서의 항목 최대 수명이며, 이 작업에 대한 Memcache 제한 시간 정책을 재정의합니다.
`max_memcache_items`	`int`	컨텍스트 Memcache 메서드의 자동 배치 처리 기능에 대한 최대 배치 크기입니다. 예를 들어 기본 크기가 `max_memcache_items`(100)인 Memcache 집합 작업은 최대 100개까지 단일 `set_multi` 작업으로 결합됩니다.
일부 트랜잭션 관련 함수의 경우, 다음 트랜잭션 옵션을 사용할 수 있습니다(위에 나열한 상속된 컨텍스트 옵션과 함께).
옵션	유형	설명
`xg`	`bool`	교차 그룹(`XG`) 트랜잭션을 허용합니다. 기본적으로 `False`개입니다.
`propagation`	`int`	NDB는 '중첩 트랜잭션'이라 하는 트랜잭션 내의 트랜잭션을 제한적으로 지원합니다. 코드가 중첩 트랜잭션을 시작하려는 경우, 전파 매개변수는 수행되는 작업을 제어합니다. `@ndb.transactional`의 전파 정책은 기본적으로 `ALLOWED`입니다. `ndb.transaction()`의 전파 정책은 기본적으로 `NESTED`입니다. `NESTED` 정책은 NDB에서 지원되지 않으므로 코드가 `BadRequestError` 예외를 발생시킵니다. 이 경우, NDB는 프로그래머가 중첩 트랜잭션의 한계에 대해 명확히 알 수 있도록 지원되지 않는 기본값을 설정합니다. 전파 매개변수는 다음 값 중 하나일 수 있습니다. `ndb.TransactionOptions.NESTED` 외부 정책이 커밋되면 `NESTED` 전파 정책은 외부와 내부 트랜잭션의 모든 변경 내용을 함께 커밋합니다. 그러나 내부 트랜잭션에서 예외가 발생하면 여기에 있는 모든 변경 사항이 삭제되지만 외부 트랜잭션은 선택적으로 복구되고 계속 진행될 수 있습니다. `NESTED` 정책은 지원되지 않습니다. 이 정책을 사용하면 코드가 `BadRequestError` 예외를 발생시킵니다. `ndb.TransactionOptions.MANDATORY` 항상 기존 트랜잭션을 전파합니다. 기존 트랜잭션이 없으면 예외를 발생시킵니다. 이 정책을 사용하는 함수에서 예외가 발생하면 예외 포착 및 외부 트랜잭션 커밋이 안전하지 않을 수 있으며, 함수로 인해 외부 트랜잭션이 잘못된 상태로 남겨질 수 있습니다. `ndb.TransactionOptions.ALLOWED` 기존 트랜잭션이 있으면 이 트랜잭션을 전파합니다. 이 정책을 사용하는 함수에서 예외가 발생하면 예외 포착 및 외부 트랜잭션 커밋이 안전하지 않을 수 있으며, 함수로 인해 외부 트랜잭션이 잘못된 상태로 남겨질 수 있습니다. `ndb.TransactionOptions.INDEPENDENT` 항상 모든 기존 트랜잭션을 '일시중지'하고 새 트랜잭션을 사용합니다. 항목이 호출자 트랜잭션과 일관성을 유지하지 않으므로, 이 정책을 사용하는 함수는 새 트랜잭션에서 읽은 항목을 반환하지 않습니다.
`retries`	`int`	트랜잭션이 실패하는 경우, 자동으로 다시 시도하는 횟수입니다. 0은 한 번만 시도하고 다시 시도하지 않음을 의미합니다.

캐싱으로 인해 옵션이 무시되는 경우도 있습니다. 예를 들어 컨텍스트 내 캐시에서 만족되는 읽기 작업의 RPC 기한을 지정하면 이 기한은 무시됩니다. 한편, 인식할 수 없는 옵션은 TypeError를 발생시킵니다.

자동 일괄 처리가 적용되면 다른 옵션을 포함한 작업이 함께 그룹화됩니다. 예를 들어 put_async()를 사용하여 일부 항목을 deadline = 5로 작성하고 다른 일부 항목을 기한을 지정하지 않은 채 작성한 후 모두 자동 일괄 처리할 수 있는 경우 기본 RPC 기한이 5이더라도 자동 일괄 처리기가 deadline = 5인 항목 그룹에 1개, 다른 그룹에 1개 등 개별 RPC 호출을 총 2개 만듭니다. 이는 지정된 옵션이 RPC 작업과 무관한 경우에도 적용됩니다(예: ndb_should_cache).