附註:強烈建議建構新應用程式的開發人員使用 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
值會轉換成 Pythonlong
值。以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
動態屬性中)。 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)
-
blobstore.BlobKey
-
Blobstore 值的鍵,在上傳此值時由 Blobstore 產生。
-
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
。如需可能的編碼值,請參閱標準編碼清單。不同於簡單的
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("larry@example.com")
在 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 (206) 555-1212")
在 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
值會轉換成 Pythonlong
值。以int
所儲存的資料值會當做long
傳回。如果指派的
long
超過 64 位元,則系統只會儲存最低有效的 64 位元。 - 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
後 (或是未指定 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
) 值的清單屬性類似。 - class StringProperty(verbose_name=None, multiline=False, ...)
-
一個短字串,採用 Python
str
或unicode
(basestring
) 值 (不得超過 1500 位元組)。StringProperty
值已建立索引,且可用於篩選器和排序順序。如果 multiline 為
False
,該值不能包含換行字元。djangoforms
程式庫在資料模型中,會用此值強制區分文字欄位與文字區域欄位,其他程式庫可能也會用在類似的用途上。如果需要字串屬性,此值不可以是空白字串。
- 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