類型和 Property 類別

附註：我們強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫，因為 NDB 用戶端程式庫與本用戶端程式庫相較之下有幾個優點，例如能透過 Memcache API 自動將實體加入快取。如果您目前使用的是舊版的 DB 用戶端程式庫，請參閱從 DB 至 NDB 的遷移指南。

App Engine Datastore 支援一組固定的資料實體屬性值類型。 Property 類別可定義新類型，以便在基礎值類型之間進行轉換，而值類型可直接與 Expando 動態屬性和 ListProperty 匯總屬性模型搭配使用。

下表列出值會直接對應到基礎資料類型的 Property 類別。這些值類型均可使用在 Expando 動態屬性或是 ListProperty 匯總類型上。

Property 類別	值類型	排列順序
IntegerProperty	int long (64 位元)	數字
FloatProperty	float	數字
BooleanProperty	bool	False < True
StringProperty	str unicode	Unicode (str 會視為 ASCII)
TextProperty	db.Text	無
ByteStringProperty	ByteString	位元組順序
BlobProperty	db.Blob	無
DateProperty TimeProperty DateTimeProperty	datetime.date datetime.time datetime.datetime	依時間順序
GeoPtProperty	db.GeoPt	依照緯度、 然後經度
PostalAddressProperty	db.PostalAddress	Unicode
PhoneNumberProperty	db.PhoneNumber	Unicode
EmailProperty	db.Email	Unicode
UserProperty	users.User	電子郵件地址 依 Unicode 順序。請注意，根據 UserProperty 類別說明下方的附註，請盡量避免使用 UserProperty。
IMProperty	db.IM	Unicode
LinkProperty	db.Link	Unicode
CategoryProperty	db.Category	Unicode
RatingProperty	db.Rating	數字
ReferenceProperty SelfReferenceProperty	db.Key	依路徑元素 (kind, identifier, kind, identifier...)
blobstore.BlobReferenceProperty	blobstore.BlobInfo	位元組順序
ListProperty StringListProperty	支援類型的 list	如為遞增，從最小的元素遞增； 如為遞減，從最大的元素遞減

資料儲存庫值類型

下列類型為 Datastore 實體可能的屬性值。請參閱上方的清單，瞭解與 Model 定義搭配使用的對應 Property 類別。

除了 Python 標準類型和 users.User 之外，本節所述的所有類別皆由 google.appengine.ext.db 模組提供。

str或unicode

一個短字串 (不得超過 1500 位元組)。

系統會假設 str 值是使用 ascii 編解碼編碼的文字，並在儲存前將其轉換為 unicode 值。資料儲存庫會以 unicode 值的形式傳回該值。如果是使用其他編解碼的短字串，請使用 unicode 值。

資料儲存庫會將短字串建立索引，可用於篩選器和排序順序。如果是超過 1500 個位元組的文字字串 (且未建立索引)，請使用 Text 例項。如果是超過 1500 個位元組且未經編碼的位元組字串 (也未建立索引)，則使用 Blob 例項。如果是應建立索引，且不超過 1500 個位元組的未經編碼非文字位元組字串 (非字元)，則使用 ByteString 例項。

「模型屬性」： StringProperty

bool

布林值 (True 或 False)。

「模型屬性」： BooleanProperty

int或long

整數值，最多 64 位元。

Python int 值會在儲存前轉換為 Python long 值。儲存為 int 的值會以 long 的形式傳回。

如果指派的 long 超過 64 位元，則系統只會儲存最低有效的 64 位元。

「模型屬性」： IntegerProperty

float

浮點數。

「模型屬性」： FloatProperty

datetime.datetime

日期和時間。請參閱 datetime 模組說明文件。

如果 datetime 值具有 tzinfo 屬性，則會轉換成世界標準時間時區來儲存。資料儲存庫會以 UTC 格式傳回值，tzinfo 為 None。如果應用程式需要將日期和時間值設為特定時區，則必須在更新值時正確設定 tzinfo，並在存取值時將值轉換為時區。

部分程式庫會使用 TZ 環境變數來控制套用到日期時間值上的時區。App Engine 會將這個環境變數設為 "UTC"。請注意，在應用程式中變更此變數，並不會更改某些日期時間函式的行為，因為對環境變數的變更無法在 Python 程式碼之外顯示出來。

如果只是要將值轉換成為特定時區，或是轉換特定時區的值，請採用自訂 datetime.tzinfo 來轉換資料儲存庫中的值：

import datetime
import time

class Pacific_tzinfo(datetime.tzinfo):
    """Implementation of the Pacific timezone."""
    def utcoffset(self, dt):
        return datetime.timedelta(hours=-8) + self.dst(dt)

    def _FirstSunday(self, dt):
        """First Sunday on or after dt."""
        return dt + datetime.timedelta(days=(6-dt.weekday()))

    def dst(self, dt):
        # 2 am on the second Sunday in March
        dst_start = self._FirstSunday(datetime.datetime(dt.year, 3, 8, 2))
        # 1 am on the first Sunday in November
        dst_end = self._FirstSunday(datetime.datetime(dt.year, 11, 1, 1))

        if dst_start <= dt.replace(tzinfo=None) < dst_end:
            return datetime.timedelta(hours=1)
        else:
            return datetime.timedelta(hours=0)
    def tzname(self, dt):
        if self.dst(dt) == datetime.timedelta(hours=0):
            return "PST"
        else:
            return "PDT"

pacific_time = datetime.datetime.fromtimestamp(time.mktime(utc_time.timetuple()), Pacific_tzinfo())

請參閱 datetime 模組說明文件 (包括 datetime.tzinfo)。請參閱第三方模組 pytz，但請注意，pytz 發布版本包含許多檔案。

DateTimeProperty 模型屬性類別含有許多功能，例如可自動使用儲存模型執行個體的日期與時間。這些屬於模型功能，不可用於原始資料儲存庫值 (例如在 Expando 動態屬性中)。

模型屬性： DateTimeProperty、 DateProperty、 TimeProperty

list

一份值清單，每個值都是其中一種支援的資料類型。

將 list 當做 Expando 動態屬性的值使用時，不可為空白清單。這是因為值清單的儲存方式的緣故：當清單屬性沒有任何項目時，資料儲存庫中也會沒有內容可以呈現。您可以使用靜態屬性和 ListProperty 類別來代表屬性的空清單值。

「模型屬性」： ListProperty

db.Key

另一個資料儲存庫實體的鍵。

附註：金鑰字串上限為 1500 個位元組。

m = Employee(name="Susan", key_name="susan5")
m.put()
e = Employee(name="Bob", manager=m.key())
e.put()

m_key = db.Key.from_path("Employee", "susan5")
e = Employee(name="Jennifer", manager=m_key)

「模型屬性」： ReferenceProperty, SelfReferenceProperty

blobstore.BlobKey

Blobstore 值的鍵，在上傳此值時由 Blobstore 產生。

「模型屬性」： blobstore.BlobReferenceProperty

users.User

使用「Google 帳戶」的使用者。

使用者變更電子郵件地址時，資料儲存庫中的 user.User 值不會更新。因此，強烈建議您避免將 users.User 儲存為 UserProperty 值，因為這會包含電子郵件地址和專屬 ID。如果使用者變更電子郵件地址，但您還是使用先前儲存的 user.User 來比對新的 user.User 值，兩者將無法配對。請改為採用 user.User 值的 user_id() 做為使用者的穩定專屬 ID。

「模型屬性」： UserProperty

class Blob(arg=None)

二進位資料，以位元組字串為格式。這是內建 str 類型的子類別。

Blob 屬性沒有建立索引，而且無法用於篩選器或排序順序。

Blob 用於圖片等二進位資料，這個函式會採用 str 值，但這個值會儲存為位元組字串，而不會以文字編碼。對於大型文字資料請使用 Text 例項。

「模型屬性」： BlobProperty

class MyModel(db.Model):
    blob = db.BlobProperty()

m = MyModel()
m.blob = db.Blob(open("image.png", "rb").read())

在 XML 中，無論 Blob 是否包含二進位資料，都是以 Base-64 編碼。

class ByteString(arg)

短 blob 值 (即「位元組字串」)，不得超過 1500 個位元組。ByteString 是 str 的子類別，並將未編碼的 str 值做為其建構函式的引數。

ByteStrings 由資料儲存庫建立索引，可用於篩選器和排序順序。如果是超過 1500 個位元組的位元組字串 (且未建立索引)，請使用 Blob 例項。如果是經過編碼的文字資料，請使用 str (短、已編入索引) 或 Text (長、未編入索引)。

「模型屬性」： ByteStringProperty

class Text(arg=None, encoding=None)

長字串。這是內建 unicode 類型的子類別。

arg 為 unicode 或 str 值。如果 arg 是 str，會使用 encoding 指定的編碼進行剖析；如果未指定編碼，則為 ascii。如需可能的編碼值，請參閱標準編碼清單。

與實體屬性不同，Text 屬性的值為簡單的 str 或 unicode，長度可超過 1500 個位元組。然而，Text 屬性並未編入索引，且無法用於篩選器或排序順序。

「模型屬性」： TextProperty

class MyModel(db.Model):
    text = db.TextProperty()

m = MyModel()
m.text = db.Text(u"kittens")

m.text = db.Text("kittens", encoding="latin-1")

class Category(tag)

一種類別或是「標記」，這是內建 unicode 類型的子類別。

「模型屬性」： CategoryProperty

class MyModel(db.Model):
    category = db.CategoryProperty()

m = MyModel()
m.category = db.Category("kittens")

在 XML 中，這是 Atom Category 元素。

class Email(email)

電子郵件地址。這是內建 unicode 類型的子類別。

屬性類別或值類別都不會執行電子郵件地址驗證，只會儲存值。

「模型屬性」： EmailProperty

class MyModel(db.Model):
    email_address = db.EmailProperty()

m = MyModel()
m.email_address = db.Email("[e-mail]")

在 XML 中，這是 gd:email 元素。

class GeoPt(lat, lon=None)

由浮點經緯度座標呈現的地理點。

「模型屬性」： GeoPtProperty

在 XML 中，這是 georss:point 元素。

class IM(protocol, address=None)

即時通訊控制代碼。

「protocol」是即時通訊服務的標準網址，以下為可能的值：

通訊協定	說明
sip	SIP/SIMPLE
xmpp	XMPP/Jabber
http://aim.com/	AIM
http://icq.com/	ICQ
http://messenger.msn.com/	MSN Messenger
http://messenger.yahoo.com/	Yahoo Messenger
http://sametime.com/	Lotus Sametime
http://gadu-gadu.pl/	Gadu-Gadu
不明	未知或未指定

「address」是控制代碼的地址。

「模型屬性」： IMProperty

class MyModel(db.Model):
    im = db.IMProperty()

m = MyModel()
m.im = db.IM("http://example.com/", "Larry97")

在 XML 中，這是 gd:im 元素。

class Link(link)

完整網址。這是內建 unicode 類型的子類別。

「模型屬性」： LinkProperty

class MyModel(db.Model):
    link = db.LinkProperty()

m = MyModel()
m.link = db.Link("http://www.google.com/")

在 XML 中，這是 Atom Link 元素。

class PhoneNumber(phone)

一組使用者可判讀的電話號碼。這是內建 unicode 類型的子類別。

「模型屬性」： PhoneNumberProperty

class MyModel(db.Model):
    phone = db.PhoneNumberProperty()

m = MyModel()
m.phone = db.PhoneNumber("1 [phone]")

在 XML 中，這是 gd.phoneNumber 元素。

class PostalAddress(address)

一個郵寄地址，這是內建 unicode 類型的子類別。

「模型屬性」： PostalAddressProperty

class MyModel(db.Model):
    address = db.PostalAddressProperty()

m = MyModel()
m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")

在 XML 中，這是 gd:postalAddress 元素。

class Rating(rating)

一個由使用者提供的內容片段評分，為 0 到 100 之間的整數。這是內建 long 類型的子類別。此類別會驗證該值是否為 0 到 100 之間的整數，並在值為無效時引發 BadValueError。

「模型屬性」： RatingProperty

class MyModel(db.Model):
    rating = db.RatingProperty()

m = MyModel()
m.rating = db.Rating(97)

在 XML 中，這是 gd:rating 元素。

Property 類別

所有 google.appengine.ext.db 提供的模型屬性類別皆為 Property 基本類別中的子類別，可支援基本建構函式的所有引數。如需引數的詳細資訊，請參閱基本類別說明文件。

google.appengine.ext.db 套件提供下列模型屬性類別：

class BlobProperty(...)

一個未解譯的二進位資料集。

Blob 資料為位元組字串。如果是可能會用到編碼的文字資料，請使用 TextProperty。

「值類型」： Blob

class BooleanProperty(...)

布林值 (True 或 False)。

「值類型」： bool

class ByteStringProperty(verbose_name=None, ...)

短 blob 值 (即「位元組字串」)，不得超過 1500 個位元組。

ByteStringProperty 值會建立索引，可用於篩選器和排序順序。

與 StringProperty 類似，但該值不會以任何方式編碼，只會儲存位元組。

如果需要 ByteStringProperty，則值不得為空白字串。

「值類型」： ByteString

class CategoryProperty(...)

一種類別或是「標記」，描述性的字詞或詞組。

「值類型」： Category

class DateProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

不含時段的日期，詳情請參閱 DateTimeProperty。

「值類型」：datetime.date；在內部會轉換成 datetime.datetime

class DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

日期和時間。

如果 auto_now 為 True，每當將模型例項儲存在資料儲存庫中時，都會將該屬性值設為目前的時間，並覆寫該屬性之前的值。很適合用於追蹤模型例項「上次修改時間」的日期時間。

如果 auto_now_add 為 True，除非已為該屬性指派值，否則第一次將模型例項儲存在資料儲存庫中時，會將屬性值設為目前時間。很適合用於儲存模型例項的「已建立」日期時間。

日期時間值會使用世界標準時間時區值來儲存，並以相同格式傳回。如要進一步瞭解如何管理時區，請參閱 datetime.datetime。

「值類型」： datetime.datetime

class EmailProperty(...)

電子郵件地址。

屬性類別或值類別都不會執行電子郵件地址驗證，只會儲存值。

「值類型」： Email

class FloatProperty(...)

浮點數。

「值類型」： float

class GeoPtProperty(...)

由浮點經緯度座標呈現的地理點。

「值類型」： GeoPt

class IMProperty(...)

即時通訊控制代碼。

「值類型」： IM

class IntegerProperty(...)

整數值，最多 64 位元。

Python int 值會在儲存前轉換為 Python long 值。儲存為 int 的值會以 long 的形式傳回。

如果指派的 long 超過 64 位元，則系統只會儲存最低有效的 64 位元。

「值類型」：int 或 long

class LinkProperty(...)

完全符合的網址。

「值類型」： Link

class ListProperty(item_type, verbose_name=None, default=None, ...)

一份由 item_type 指定的類型值清單。

在查詢中，將清單屬性與值進行比較，可對清單成員執行測試：list_property = value 會測試值是否出現在清單的任一位置，list_property < value 會測試清單成員是否有任何值小於指定值，依此類推。

查詢無法比較兩份清單值。如果要測試兩份清單的相等性，也須單獨測試每個元素的成員資格。

item_type 是清單內的項目類型，例如 Python 類型或類別。清單值中的所有項目必須為指定的類型。item_type 必須為資料儲存庫值類型之一，且不能為 list。

ListProperty 的值不得為 None。但可以是空白清單。將預設引數指定為 None 後 (或是未指定 預設引數時)，該屬性的預設值即為空白清單。

提示：由於 ListProperty 匯總類型不會使用 Property 類別，因此 Property 類別的功能 (例如自動值和驗證) 不會自動套用至清單值的成員。如果想用 Property 類別驗證成員值，可以將類別實例化，並針對該值呼叫類別的 validate() 方法。

default 是清單屬性的預設值。如果是 None，預設值為空白清單。清單屬性可定義自訂驗證器，禁止使用空清單。

如要進一步瞭解清單屬性與值的詳細資訊，請參閱建立資料模型頁面。

「值類型」：指定類型值的 Python list

class PhoneNumberProperty(...)

一組使用者可判讀的電話號碼。

「值類型」： PhoneNumber

class PostalAddressProperty(...)

一個郵寄地址。

「值類型」： PostalAddress

class RatingProperty()

一個由使用者提供的內容片段評分，為 0 到 100 之間的整數。

「值類型」： Rating

class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)

其他模型例項的參照。例如，參照可能會指出含有該屬性的模型與該屬性參照之模型間的多對一關係。

reference_class 是參照模型例項的模型類別。如果有指定，則只有該類別的模型例項可以指派給此屬性。如果是 None，則任何模型例項都可以是此屬性的值。

collection_name 是要提供給所參照模型類別的屬性名稱。對於參照該實體的所有實體，該屬性值為 Query。如果未設定 collection_name，系統會使用 modelname_set (以小寫字母加上 _set 的參照模型名稱)。

注意：如果參照相同模型類別的同一個模型內有多個屬性，就必須設定 collection_name。否則，系統會在產生預設名稱時擲回 DuplicatePropertyError。

ReferenceProperty 會自動將模型例項做為屬性值進行參照和取消參照：模型例項可直接指派至參照屬性，並使用該屬性的鍵。您可以將 ReferenceProperty 值視為模型例項使用，並在首次以這種方式使用時擷取資料儲存庫實體，以及建立模型例項。未受影響的參照屬性不會查詢不需要的資料。

class Author(db.Model):
    name = db.StringProperty()

class Story(db.Model):
    author = db.ReferenceProperty(Author)

story = db.get(story_key)
author_name = story.author.name

author = db.get(author_key)
stories_by_author = author.story_set.get()

與 Key 值一樣，參照屬性值可以參照不存在的資料實體。如果刪除資料儲存庫中的參照實體，則該實體的參照不會隨之更新。存取不存在的實體會引發 ReferencePropertyResolveError。

刪除實體並不會刪除參照屬性所參照的實體。

「值類型」： db.Key

class SelfReferenceProperty(verbose_name=None, collection_name=None, ...)

對相同類別的其他模型例項的參照 (請參閱 ReferenceProperty)。

「值類型」： db.Key

class StringListProperty(verbose_name=None, default=None, ...)

與 Python str 或 unicode (basestring) 值的清單屬性類似。

值類型：Python list 的 str 或 unicode 值

class StringProperty(verbose_name=None, multiline=False, ...)

一個短字串，採用 Python str 或 unicode (basestring) 值，不得超過 1500 個位元組。

StringProperty 值會建立索引，可用於篩選器和排序順序。

如果 multiline 為 False，該值不能包含換行字元。djangoforms 程式庫會使用這項功能，在資料模型中強制區分文字欄位和 textarea 欄位，其他人也可以將其用於類似用途。

如果需要字串屬性，此值不可以是空白字串。

「值類型」： str 或 unicode

class TextProperty()

長字串。

與 StringProperty 不同，TextProperty 值的長度可超過 1500 個位元組。然而，TextProperty 值並未建立索引，且無法用於篩選器或排序順序。

TextProperty 值會以文字編碼儲存文字。如果是二進位資料，則使用 BlobProperty。

如果需要文字屬性，此值不可以是空白字串。

「值類型」： Text

class TimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

沒有日期的時段，採用 Python 標準程式庫 datetime.time 值。詳情請參閱 DateTimeProperty。

「值類型」：datetime.time；在內部會轉換成 datetime.datetime

class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)

重要事項：強烈建議您不要儲存 UserProperty，因為這個項目含有電子郵件地址和使用者的唯一識別碼。如果使用者變更電子郵件地址，但您還是使用先前儲存的 User 來比對新的 User 值，兩者將無法配對。

使用「Google 帳戶」的使用者。

如果 auto_current_user 為 True，每當將模型例項儲存在資料儲存庫中時，都會將該屬性值設為目前登入的使用者，並覆寫該屬性之前的值。很適合用於追蹤修正模型例項的使用者。

如果 auto_current_user_add 為 True，除非已為該屬性指派值，否則第一次將模型例項儲存在資料儲存庫中時，會將屬性值設為目前登入的使用者。很適合用於追蹤修正模型例項的使用者，因為該使用者可能與之後的修改者不相同。

UserProperty 不接受預設值。模型類別第一次匯入時會設定預設值，其中的匯入快取可能並非目前登入的使用者。

「值類型」： users.User