類型和 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	按路徑元素 (種類、ID、 種類、ID...)
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 屬性，則會轉換成世界標準時間時區來儲存。資料儲存庫傳回的值為世界標準時間，包含 None 的 tzinfo。如果是需要特定時區的日期時間值的應用程式，則必須在更新值時正確設定 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 值儲存，因為唯一識別碼內也會包含電子郵件地址。如果使用者變更電子郵件地址，但您還是使用先前儲存的 user.User 來比對新的 user.User 值時，兩者將無法配對。請考慮改為使用 user.User 值的 user_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。如需編碼可能的值，請參閱標準編碼清單。

不同於簡單的 str 或 unicode 的實體屬性值，Text 屬性可超過 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 必須為 datastore value types 之一，且不能為 list。

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

提示：因為 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 str 的 list 或 unicode 值。

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

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

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

如果 multiline 為 False，該值不能包含換行字元。djangoforms 程式庫在資料模型中，會用此值強制區分文字欄位與文字區域欄位，其他程式庫可能也會用在類似的用途上。

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

「值類型」：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，因為此屬性含有電子郵件地址和使用者的專屬 ID。如果使用者變更了電子郵件地址，但您還是使用先前儲存的 User 來比對新的 User 值，兩者將無法配對。

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

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

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

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

「值類型」：users.User