Package google.golang.org/appengine/datastore (v1.6.8)

Le package Datastore fournit un client pour le service de datastore d'App Engine.

Opérations de base

Les entités constituent l'unité de stockage et sont associées à une clé. Une clé comporte une clé parent facultative, un identifiant d'application de chaîne, un kind de chaîne (aussi connu en tant que type d'entité) et un StringID ou un IntID. Un StringID est également connu en tant que nom d'entité ou nom de clé.

Il est possible de créer une clé avec un "StringID" et un "IntID" nuls : c'est ce que l'on appelle une clé incomplète, qui ne fait référence à aucune entité enregistrée. L'ajout d'une entité au datastore avec une clé incomplète entraîne la création d'une clé unique pour cette entité, avec un "IntID" non nul.

Le contenu d'une entité correspond au mappage des noms de champ sensibles à la casse sur des valeurs. Les types de valeurs reconnus sont les suivants :

  • Entiers signés (int, int8, int16, int32 et int64)
  • bool,
  • string,
  • float32 et float64,
  • []octet (longueur maximale de 1 mégaoctet),
  • tout type dont le type sous-jacent est l'un des types déclarés ci-dessus,
  • ByteString,
  • *Key,
  • time.Time (stocké avec une précision de l'ordre de la microseconde),
  • appengine.BlobKey,
  • appengine.GeoPoint,
  • Structures dont les champs sont tous des types de valeurs valides,
  • tranches de l'un des éléments ci-dessus.

Les tranches de structures sont valides, de même que les structures qui contiennent des tranches. Cependant, si une structure en contient une autre, alors une de ces structures au maximum peut être répétée. Cela disqualifie les types de structure définis de manière récursive : toute structure "T" qui contient "[]T" (directement ou indirectement).

Les fonctions "Get" et "Put" chargent et sauvegardent le contenu d'une entité. Celui-ci est généralement représenté par un pointeur de structure.

Exemple de code :

type Entity struct {
    Value string
}

func handle(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)

    k := datastore.NewKey(ctx, "Entity", "stringID", 0, nil)
    e := new(Entity)
    if err := datastore.Get(ctx, k, e); err != nil {
        http.Error(w, err.Error(), 500)
        return
    }

    old := e.Value
    e.Value = r.URL.Path

    if _, err := datastore.Put(ctx, k, e); err != nil {
        http.Error(w, err.Error(), 500)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    fmt.Fprintf(w, "old=%q\nnew=%q\n", old, e.Value)
}

Les fonctions "GetMulti", "PutMulti" et "DeleteMulti" correspondent à des versions en traitement par lot des fonctions "Get", "Put" et "Delete". Elles prennent []*Key au lieu de *Key et peuvent afficher une erreur "fonction appengine.MultiError" en cas de défaillance partielle.

Propriétés

Le contenu d'une entité peut être représenté par divers types. En règle générale, il s'agit de pointeurs de structure, mais n'importe quel type qui met en œuvre l'interface "PropertyLoadSaver" peut être utilisé. Si vous utilisez un pointeur de structure, vous n'avez pas à mettre en œuvre explicitement l'interface "PropertyLoadSaver". Le datastore sera automatiquement converti par réflexion. Si un pointeur de structure met en œuvre cette interface, ces méthodes seront privilégiées plutôt que le comportement par défaut des pointeurs de structure. Les pointeurs de structure sont des types plus forts et plus faciles à utiliser, mais les types "PropertyLoadSavers" sont plus flexibles.

Les types réels transmis ne doivent pas nécessairement correspondre entre les appels "Get" et "Put", ni même entre différents appels au datastore. Il est valide d'envoyer "*PropertyList" et d'obtenir la même entité en tant que "*myStruct", ou d'envoyer "*myStruct0" et d'obtenir "*myStruct1". Sur le plan conceptuel, toute entité est enregistrée en tant que séquence de propriétés et est chargée dans la valeur de destination, propriété par propriété. Lors du chargement dans un pointeur de structure, une entité qui ne peut pas être complètement représentée (telle qu'un champ manquant) entraîne une erreur "ErrFieldMismatch". Cependant, il appartient à l'appelant de décider si cette erreur est fatale, récupérable ou si elle peut être ignorée.

Par défaut, pour les pointeurs de structure, toutes les propriétés sont potentiellement indexées et le nom de la propriété est identique au nom du champ (et doit donc commencer par une lettre majuscule).

Les champs peuvent présenter un tag datastore:"name,options". Le nom du tag correspond au nom de la propriété. Celui-ci doit être constitué d'un ou plusieurs identifiants Go valides reliés par ".", mais peut commencer par une lettre minuscule. Un nom de tag vide signifie qu'il faut simplement utiliser le nom du champ. Le nom de tag "-" signifie que le datastore ignorera ce champ.

Les seules options valides sont "omitempty" et "noindex".

Si les options incluent "omitempty" et que la valeur du champ est vide, le champ est omis au moment de la sauvegarde. Les valeurs vides sont "false", "0", toute valeur d'interface nulle, et tout tableau, tranche, carte ou chaîne de longueur nulle. Les valeurs des champs de structure ne sont jamais vides.

Si les options incluent "noindex", le champ ne sera pas indexé. Tous les champs sont indexés par défaut. Les chaînes ou les tranches d'octets de plus de 1 500 octets ne peuvent pas être indexées. Les champs utilisés pour stocker de longues chaînes et des tranches d'octets doivent présenter le tag "noindex" afin que les opérations "Put" n'échouent pas.

Pour utiliser plusieurs options en même temps, séparez-les par une virgule. L'ordre n'a pas d'importance.

Si la valeur d'"options" est "", la virgule peut être omise.

Exemple de code :

// A and B are renamed to a and b.
// A, C and J are not indexed.
// D's tag is equivalent to having no tag at all (E).
// I is ignored entirely by the datastore.
// J has tag information for both the datastore and json packages.
type TaggedStruct struct {
    A int `datastore:"a,noindex"`
    B int `datastore:"b"`
    C int `datastore:",noindex"`
    D int `datastore:""`
    E int
    I int `datastore:"-"`
    J int `datastore:",noindex" json:"j"`
}

Propriétés structurées

Si la structure qui est pointée contient d'autres structures, les structures imbriquées ou intégrées sont aplaties. Par exemple, pour les définitions suivantes :

type Inner1 struct {
    W int32
    X string
}

type Inner2 struct {
    Y float64
}

type Inner3 struct {
    Z bool
}

type Outer struct {
    A int16
    I []Inner1
    J Inner2
    Inner3
}

les propriétés d'un type "Outer" seraient équivalentes à celles du type suivant :

type OuterEquivalent struct {
    A     int16
    IDotW []int32  `datastore:"I.W"`
    IDotX []string `datastore:"I.X"`
    JDotY float64  `datastore:"J.Y"`
    Z     bool
}

Si le champ "Inner3" intégré à "Outer" présentait le tag datastore:"Foo", le champ équivalent serait le suivant: FooDotZ bool datastore:"Foo.Z".

Si une structure externe présente le tag "noindex", tous ses champs implicites aplatis sont effectivement "noindex".

Interface "PropertyLoadSaver"

Le contenu d'une entité peut également être représenté par n'importe quel type qui met en œuvre l'interface "PropertyLoadSaver". Il peut d'agir d'un pointeur de structure, mais ce n'est pas nécessairement le cas. Le package Datastore appelle la méthode "Load" lors de l'obtention du contenu de l'entité et la méthode "Save" lors de l'insertion de celui-ci. Les utilisations possibles incluent la dérivation de champs non stockés, la vérification de champs ou l'indexation d'un champ seulement si sa valeur est positive.

Exemple de code :

type CustomPropsExample struct {
    I, J int
    // Sum is not stored, but should always be equal to I + J.
    Sum int `datastore:"-"`
}

func (x *CustomPropsExample) Load(ps []datastore.Property) error {
    // Load I and J as usual.
    if err := datastore.LoadStruct(x, ps); err != nil {
        return err
    }
    // Derive the Sum field.
    x.Sum = x.I + x.J
    return nil
}

func (x *CustomPropsExample) Save() ([]datastore.Property, error) {
    // Validate the Sum field.
    if x.Sum != x.I + x.J {
        return nil, errors.New("CustomPropsExample has inconsistent sum")
    }
    // Save I and J as usual. The code below is equivalent to calling
    // "return datastore.SaveStruct(x)", but is done manually for
    // demonstration purposes.
    return []datastore.Property{
        {
            Name:  "I",
            Value: int64(x.I),
        },
        {
            Name:  "J",
            Value: int64(x.J),
        },
    }, nil
}

Le type "*PropertyList" met en œuvre "PropertyLoadSaver" et peut donc comporter le contenu d'une entité arbitraire.

Requêtes

Les requêtes récupèrent des entités en fonction de leurs propriétés ou de l’ascendance de leur clé. L'exécution d'une requête génère un itérateur de résultats : des clés ou des paires (clé, entité). Les requêtes sont réutilisables et vous pouvez appeler en toute sécurité Query.Run à partir de goroutines simultanées. L'utilisation simultanée des itérateurs n'est pas sécurisée.

Les requêtes sont immuables. Elles sont créées en appelant "NewQuery" ou dérivées d'une requête existante en appelant une méthode telle que "Filter" ou "Order", qui renvoie une nouvelle valeur de requête. Une requête est généralement construite en appelant "NewQuery" suivi d'une chaîne de zéro ou plusieurs de ces méthodes, qui sont les suivantes :

  • "Ancestor" et "Filter" limitent les entités renvoyées en exécutant une requête.
  • "Order" affecte l'ordre dans lequel elles sont renvoyées.
  • "Project" limite les champs renvoyés.
  • "Distinct" déduplique les entités projetées.
  • KeysOnly crée l'itérateur uniquement des clés, et non des paires (clé, entité).
  • Les valeurs "Start", "End", "Offset" et "Limit" définissent la sous-séquence d'entités correspondantes à renvoyer. "Start" et "End" prennent des curseurs, "Offset" et "Limit" prennent des entiers. "Start" et "Offset" affectent le premier résultat, "End" et "Limit" affectent le dernier résultat. Si "Start" et "Offset" sont définies, "Offset" est liée à "Start". Si "End" et "Limit" sont définis, la contrainte la plus ancienne l'emporte. "Limit" est liée à Start+Offset, et non à "End". Cas particulier : une limite négative signifie un nombre illimité.

Exemple de code :

type Widget struct {
    Description string
    Price       int
}

func handle(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)
    q := datastore.NewQuery("Widget").
        Filter("Price <", 1000).
        Order("-Price")
    b := new(bytes.Buffer)
    for t := q.Run(ctx); ; {
        var x Widget
        key, err := t.Next(&x)
        if err == datastore.Done {
            break
        }
        if err != nil {
            serveError(ctx, w, err)
            return
        }
        fmt.Fprintf(b, "Key=%v\nWidget=%#v\n\n", key, x)
    }
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    io.Copy(w, b)
}

Transactions

RunInTransaction exécute une fonction dans une transaction.

Exemple de code :

type Counter struct {
    Count int
}

func inc(ctx context.Context, key *datastore.Key) (int, error) {
    var x Counter
    if err := datastore.Get(ctx, key, &x); err != nil && err != datastore.ErrNoSuchEntity {
        return 0, err
    }
    x.Count++
    if _, err := datastore.Put(ctx, key, &x); err != nil {
        return 0, err
    }
    return x.Count, nil
}

func handle(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)
    var count int
    err := datastore.RunInTransaction(ctx, func(ctx context.Context) error {
        var err1 error
        count, err1 = inc(ctx, datastore.NewKey(ctx, "Counter", "singleton", 0, nil))
        return err1
    }, nil)
    if err != nil {
        serveError(ctx, w, err)
        return
    }
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    fmt.Fprintf(w, "Count=%d", count)
}

Métadonnées

Le package Datastore permet d'accéder à certaines métadonnées de datastore d'App Engine. Ces métadonnées incluent des informations sur les groupes d'entités, les espaces de nommage, les genres d'entité et les propriétés du datastore, ainsi que sur les représentations de chaque propriété.

Exemple de code :

func handle(w http.ResponseWriter, r *http.Request) {
    // Print all the kinds in the datastore, with all the indexed
    // properties (and their representations) for each.
    ctx := appengine.NewContext(r)

    kinds, err := datastore.Kinds(ctx)
    if err != nil {
        serveError(ctx, w, err)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    for _, kind := range kinds {
        fmt.Fprintf(w, "%s:\n", kind)
        props, err := datastore.KindProperties(ctx, kind)
        if err != nil {
            fmt.Fprintln(w, "\t(unable to retrieve properties)")
            continue
        }
        for p, rep := range props {
            fmt.Fprintf(w, "\t-%s (%s)\n", p, strings.Join(rep, ", "))
        }
    }
}

Variables

ErrInvalidEntityType, ErrInvalidKey, ErrNoSuchEntity

var (
	// ErrInvalidEntityType is returned when functions like Get or Next are
	// passed a dst or src argument of invalid type.
	ErrInvalidEntityType = errors.New("datastore: invalid entity type")
	// ErrInvalidKey is returned when an invalid key is presented.
	ErrInvalidKey = errors.New("datastore: invalid key")
	// ErrNoSuchEntity is returned when no entity was found for a given key.
	ErrNoSuchEntity = errors.New("datastore: no such entity")
)

OK

var Done = errors.New("datastore: query has no more results")

La valeur Done est renvoyée lorsque l'itération d'une requête est terminée.

ErrConcurrentTransaction

var ErrConcurrentTransaction = errors.New("datastore: concurrent transaction")

La valeur "ErrConcurrentTransaction" est renvoyée lorsqu'un rollback est effectué pour une transaction en raison d'un conflit avec une transaction simultanée.

Fonctions

func AllocateIDRange 

func AllocateIDRange(c context.Context, kind string, parent *Key, start, end int64) (err error)

AllocateIDRange alloue une plage d'identifiants avec des points de terminaison spécifiques. Les valeurs inférieure et supérieure de la plage sont inclusives. Une fois ces identifiants alloués, vous pouvez les attribuer manuellement aux nouvelles entités.

L'outil d'attribution automatique d'identifiants du datastore n'affecte jamais une clé déjà attribuée (que ce soit par attribution automatique d'identifiants ou par un appel explicite "AllocateIDs"). Par conséquent, les entités écrites dans la plage de clés donnée ne seront jamais remplacées. Toutefois, l'écriture d'entités auxquelles des clés ont été attribuées manuellement dans cette plage risque de remplacer des entités existantes (ou de nouvelles entités écrites par une requête distincte) en fonction de l'erreur renvoyée.

N'utilisez cette méthode que si vous souhaitez réserver une plage d'identifiants numériques existante (par exemple, pour charger en bloc des entités ayant déjà des identifiants). Si les ID que vous recevez n'ont pas d'importance, utilisez plutôt la AllocateIDs.

AllocateIDRange renvoie "nil" si la plage est correctement allouée. Si une ou plusieurs entités avec déjà un ID dans la plage donnée existent déjà, elles renvoient une erreur KeyRangeCollisionError. Si le datastore a déjà mis en cache les ID dans cette plage (par exemple, d'un appel précédent à AllocateIDRange), il renvoie une erreur KeyRangeContentionError. Les erreurs d'autres types indiquent des problèmes avec les arguments ou une erreur renvoyée directement par le datastore.

func AllocateIDs

func AllocateIDs(c context.Context, kind string, parent *Key, n int) (low, high int64, err error)

La fonction AllocateIDs renvoie une plage de n ID entiers avec la combinaison de "kind" et de "parent" donnée. La valeur de "kind" ne peut pas être vide, mais la valeur de "parent" peut être "nil". Les ID de la plage renvoyée ne seront pas utilisés par le générateur de séquence d'ID automatique du datastore et peuvent être utilisés avec la fonction NewKey sans conflit.

La valeur inférieure de la plage est inclusive et la valeur supérieure de la plage est exclusive. En d'autres termes, les ID entiers valides "x" satisfont "low <= x && x < high".

Si aucune erreur n'est renvoyée, "low + n == high".

func Delete 

func Delete(c context.Context, key *Key) error

La fonction Delete supprime l'entité de la clé donnée.

func DeleteMulti 

func DeleteMulti(c context.Context, key []*Key) error

La fonction DeleteMulti est une version traitement par lot de la fonction Delete.

func EnableKeyConversion 

func EnableKeyConversion(ctx context.Context)

La fonction "EnableKeyConversion" assure la compatibilité des clés encodées avec la bibliothèque cliente Cloud Datastore (cloud.google.com/go/datastore). Les clés encodées générées par la bibliothèque cliente Cloud Datastore sont décodées en clés de datastore App Engine.

Le contexte fourni doit être un contexte App Engine s'il s'exécute dans un environnement d'exécution App Engine de première génération. Vous pouvez l'appeler dans le gestionnaire /_ah/start. Vous pouvez appeler la méthode plusieurs fois en toute sécurité. Cette méthode est peu coûteuse, et peut donc être insérée en tant que middleware.

L'activation de la compatibilité avec les clés n'affecte pas le format d'encodage utilisé par Key.Encode, elle ne développe que le type de clés pouvant être décodées avec DecodeKey.

func Get 

func Get(c context.Context, key *Key, dst interface{}) error

La fonction Get charge l'entité stockée pour "k" dans "dst", qui doit être un pointeur de structure ou mettre en œuvre "PropertyLoadSaver". S'il n'existe aucune entité pour la clé, la fonction Get affiche "ErrNoSuchEntity".

Les valeurs des champs de structure sans correspondance de "dst" ne sont pas modifiées et les champs de type tranche correspondants ne sont pas réinitialisés avant leur ajout. En particulier, il est recommandé de faire passer un pointeur sur une structure de valeur zéro à chaque appel de "Get".

"ErrFieldMismatch" est renvoyé lorsqu'un champ doit être chargé dans un type différent de celui où il a été stocké, lorsqu'il manque un champ ou que le champ n'est pas exporté dans la structure de destination. "ErrFieldMismatch" n'est renvoyé que si "dst" est un pointeur de structure.

func GetMulti 

func GetMulti(c context.Context, key []*Key, dst interface{}) error

La fonction GetMulti est une version traitement par lot de la fonction Get.

"dst" doit correspondre à "[]S", "[]*S", "[]I" ou "[]P", pour un type de structure "S", un type d'interface "I" ou un type "P" autre qu'un pointeur et qu'une interface, tel que "P" ou "*P" mette en œuvre "PropertyLoadSaver". S'il correspond à "[]I", chaque élément doit être un argument "dst" valide pour "Get" : il doit s'agir d'un pointeur de structure ou il doit mettre en œuvre "PropertyLoadSaver".

En tant que cas particulier, le type "PropertyList" est non valide pour "dst", même si "PropertyList" est une tranche de structure. Il est considéré comme non valide pour éviter d'être transmis par erreur lorsque "[]PropertyList" est souhaité.

func KindProperties 

func KindProperties(ctx context.Context, kind string) (map[string][]string, error)

La fonction KindProperties affiche toutes les propriétés indexées pour le genre donné. Les propriétés sont affichées sous forme de mappage de noms de propriété sur une tranche des types de représentation. Les types de représentation pour les types de propriété Go compatibles sont les suivants :

"INT64":     signed integers and time.Time
"DOUBLE":    float32 and float64
"BOOLEAN":   bool
"STRING":    string, []byte and ByteString
"POINT":     appengine.GeoPoint
"REFERENCE": *Key
"USER":      (not used in the Go runtime)

func Kinds 

func Kinds(ctx context.Context) ([]string, error)

La fonction Kinds affiche les noms de tous les genres dans l'espace de nommage actuel.

func LoadStruct 

func LoadStruct(dst interface{}, p []Property) error

La fonction "LoadStruct" charge les propriétés de "f" à "dst". "dst" doit être un pointeur de structure.

func Namespaces 

func Namespaces(ctx context.Context) ([]string, error)

La fonction Namespaces affiche tous les espaces de nommage du datastore.

func RunInTransaction

func RunInTransaction(c context.Context, f func(tc context.Context) error, opts *TransactionOptions) error

La fonction RunInTransaction exécute "f" dans une transaction. Elle appelle "f" avec un contexte de transaction "tc" que "f" doit utiliser pour toutes les opérations App Engine.

Si "f" renvoie "nil", la fonction RunInTransaction tente d'effectuer un commit de la transaction, en renvoyant "nil" si l'opération réussit. Si le commit échoue en raison d'une transaction incompatible, la fonction RunInTransaction relance "f" avec un nouveau contexte de transaction à chaque fois. L'opération est abandonnée et l'erreur "ErrConcurrentTransaction" est affichée après trois tentatives infructueuses. Le nombre de tentatives peut être configuré en spécifiant TransactionOptions.Attempts.

Si "f" renvoie une valeur différente de "nil", aucune modification apportée au datastore n'est appliquée et RunInTransaction affiche la même erreur. La fonction "f" n'est pas retentée.

Sachez que lorsque "f" affiche une valeur, le commit de la transaction n'est pas encore effectif. Le code appelant doit supposer qu'aucun commit des modifications apportées à "f" n'est effectif tant que la fonction RunInTransaction n'a pas affiché "nil".

Comme la fonction f peut être appelée plusieurs fois, elle devrait généralement être idempotente. datastore.Get n'est pas idempotent lors du rétablissement des champs de tranches.

Les transactions imbriquées ne sont pas compatibles ; "c" ne peut pas être un contexte de transaction.

ByteString

type ByteString []byte

Le type ByteString correspond à une tranche d'octets courte (jusqu'à 1 500 octets) pouvant être indexée.

Cursor

type Cursor struct {
	// contains filtered or unexported fields
}

Le type Cursor représente la position d'un itérateur. Il peut être converti à partir d'une chaîne opaque et en chaîne opaque. Un curseur peut être utilisé à partir de différentes requêtes HTTP, mais seulement avec une requête présentant les mêmes contraintes de genre, d'ancêtre, de filtre et d'ordre.

func DecodeCursor 

func DecodeCursor(s string) (Cursor, error)

La fonction DecodeCursor décode un curseur à partir de sa représentation sous forme de chaîne en base64.

func (Cursor) String 

func (c Cursor) String() string

La fonction String renvoie une représentation d'un curseur sous forme de chaîne en base64.

Entité

type Entity struct {
	Key        *Key
	Properties []Property
}

Le type Entity représente le type de valeur d'une structure imbriquée. Ce type est n'utilisé que pour une valeur de "Property".

ErrFieldMismatch

type ErrFieldMismatch struct {
	StructType reflect.Type
	FieldName  string
	Reason     string
}

"ErrFieldMismatch" est renvoyé lorsqu'un champ doit être chargé dans un type différent de celui où il a été stocké, lorsqu'il manque un champ ou que le champ n'est pas exporté dans la structure de destination. StructType est le type d'objet struct vers lequel pointe l'argument de destination transmis à Get ou à Iterator.Next.

func (*ErrFieldMismatch) Error

func (e *ErrFieldMismatch) Error() string

anonyme

type Iterator struct {
	// contains filtered or unexported fields
}

Le type Iterator correspond au résultat de l'exécution d'une requête.

func (*Iterator) Cursor 

func (t *Iterator) Cursor() (Cursor, error)

La fonction Cursor affiche un curseur pour l'emplacement actuel de l'itérateur.

func (*Iterator) Next 

func (t *Iterator) Next(dst interface{}) (*Key, error)

La fonction Next affiche la clé du résultat suivant. Lorsqu'il n'y a plus de résultats, la valeur "Done" est affichée en tant qu'erreur.

Si la requête ne représente pas que des clés et que la valeur de "dst" n'est pas "nil", elle charge également l'entité stockée pour cette clé dans le pointeur de structure ou dans l'argument "dst" de "PropertyLoadSaver", avec la même sémantique et les mêmes erreurs possibles que pour la fonction Get.

Clé

type Key struct {
	// contains filtered or unexported fields
}

Le type Key, qui correspond à la clé du datastore pour une entité stockée, est immuable.

func DecodeKey 

func DecodeKey(encoded string) (*Key, error)

La fonction DecodeKey décode une clé à partir de la représentation opaque affichée par la fonction Encode.

func NewIncompleteKey 

func NewIncompleteKey(c context.Context, kind string, parent *Key) *Key

La fonction NewIncompleteKey crée une clé incomplète. "kind" ne peut pas être vide.

func NewKey 

func NewKey(c context.Context, kind, stringID string, intID int64, parent *Key) *Key

La fonction NewKey crée une clé. "kind" ne peut pas être vide. "StringID" ou "IntID", ou les deux, doivent être nuls. Si les deux sont nuls, la clé renvoyée est incomplète. "parent" doit être une clé complète ou "nil".

func Put

func Put(c context.Context, key *Key, src interface{}) (*Key, error)

La fonction Put enregistre l'entité "src" dans le datastore avec la clé "k". "src" doit être un pointeur de structure ou mettre en œuvre "PropertyLoadSaver". S'il s'agit d'un pointeur de structure, tous les champs non exportés de cette structure sont ignorés. Si "k" est une clé incomplète, la clé renvoyée est une clé unique générée par le datastore.

func PutMulti 

func PutMulti(c context.Context, key []*Key, src interface{}) ([]*Key, error)

La fonction PutMulti est une version traitement par lot de la fonction Put.

"src" doit satisfaire aux mêmes conditions que l'argument "dst" de la fonction GetMulti.

func (*Key) AppID

func (k *Key) AppID() string

La fonction AppID affiche l'ID d'application de la clé.

func (*Key) Encode 

func (k *Key) Encode() string

La fonction Encode affiche une représentation opaque de la clé pouvant être utilisée dans HTML et les URL, et compatible avec les environnements d'exécution Python et Java.

func (*Key) Equal 

func (k *Key) Equal(o *Key) bool

La fonction Equal renvoie le fait que deux clés sont égales ou non.

func (*Key) GobDecode 

func (k *Key) GobDecode(buf []byte) error

func (*Key) GobEncode 

func (k *Key) GobEncode() ([]byte, error)

func (*Key) Incomplete 

func (k *Key) Incomplete() bool

La fonction Incomplete indique si la clé ne fait pas référence à une entité stockée. Elle indique en particulier si "StringID" et "IntID" sont nuls.

func (*Key) IntID 

func (k *Key) IntID() int64

La fonction IntID affiche l'ID de la clé sous forme d'entier, dont la valeur peut être "0".

func (*Key) Kind 

func (k *Key) Kind() string

La fonction Kind affiche le genre de la clé (également appelé type d'entité).

func (*Key) MarshalJSON 

func (k *Key) MarshalJSON() ([]byte, error)

func (*Key) Namespace 

func (k *Key) Namespace() string

La fonction Namespace affiche l'espace de nommage de la clé.

func (*Key) Parent 

func (k *Key) Parent() *Key

La fonction Parent affiche la clé parente de la clé, dont la valeur peut être "nil".

func (*Key) String 

func (k *Key) String() string

La fonction String affiche une représentation sous forme de chaîne de la clé.

func (*Key) StringID 

func (k *Key) StringID() string

La fonction StringID affiche l'ID de chaîne de la clé (également appelé nom d'entité ou nom de clé), dont la valeur peut être "".

func (*Key) UnmarshalJSON

func (k *Key) UnmarshalJSON(buf []byte) error

KeyRangeCollisionError

type KeyRangeCollisionError struct {
	// contains filtered or unexported fields
}

erreur func (*KeyRangeCollisionError) 

func (e *KeyRangeCollisionError) Error() string

KeyRangeContentionError

type KeyRangeContentionError struct {
	// contains filtered or unexported fields
}

erreur func (*KeyRangeContentionError) 

func (e *KeyRangeContentionError) Error() string

Propriété

type Property struct {
	// Name is the property name.
	Name string
	// Value is the property value. The valid types are:
	//	- int64
	//	- bool
	//	- string
	//	- float64
	//	- ByteString
	//	- *Key
	//	- time.Time
	//	- appengine.BlobKey
	//	- appengine.GeoPoint
	//	- []byte (up to 1 megabyte in length)
	//	- *Entity (representing a nested struct)
	// This set is smaller than the set of valid struct field types that the
	// datastore can load and save. A Property Value cannot be a slice (apart
	// from []byte); use multiple Properties instead. Also, a Value's type
	// must be explicitly on the list above; it is not sufficient for the
	// underlying type to be on that list. For example, a Value of "type
	// myInt64 int64" is invalid. Smaller-width integers and floats are also
	// invalid. Again, this is more restrictive than the set of valid struct
	// field types.
	//
	// A Value will have an opaque type when loading entities from an index,
	// such as via a projection query. Load entities into a struct instead
	// of a PropertyLoadSaver when using a projection query.
	//
	// A Value may also be the nil interface value; this is equivalent to
	// Python's None but not directly representable by a Go struct. Loading
	// a nil-valued property into a struct will set that field to the zero
	// value.
	Value interface{}
	// NoIndex is whether the datastore cannot index this property.
	NoIndex bool
	// Multiple is whether the entity can have multiple properties with
	// the same name. Even if a particular instance only has one property with
	// a certain name, Multiple should be true if a struct would best represent
	// it as a field of type []T instead of type T.
	Multiple bool
}

Le type Property correspond à une paire nom/valeur avec des métadonnées. Le contenu d'une entité de datastore est chargé et enregistré en tant que séquence de types "Property". Une entité peut avoir plusieurs "Properties" portant le même nom, à condition que p.Multiple soit défini sur toutes les "Properties" de cette entité portant ce nom.

func SaveStruct

func SaveStruct(src interface{}) ([]Property, error)

La fonction SaveStruct renvoie les propriétés "src" en tant que tranche de "Properties". "src" doit être un pointeur de structure.

PropertyList

type PropertyList []Property

Le type PropertyList convertit "[]Property" pour mettre en œuvre "PropertyLoadSaver".

func (*PropertyList) Load 

func (l *PropertyList) Load(p []Property) error

La fonction Load charge toutes les propriétés fournies dans "l". Elle ne commence pas par réinitialiser "*1" sur une tranche vide.

func (*PropertyList) Save 

func (l *PropertyList) Save() ([]Property, error)

La fonction Save enregistre toutes les propriétés de "l" sous forme de tranche ou de type "Property".

PropertyLoadSaver

type PropertyLoadSaver interface {
	Load([]Property) error
	Save() ([]Property, error)
}

Le type PropertyLoadSaver peut être converti à partir d'une tranche de "Property" ou en tranche de "Property".

Requête

type Query struct {
	// contains filtered or unexported fields
}

Le type Query correspond à une requête de datastore.

func NewQuery 

func NewQuery(kind string) *Query

La fonction NewQuery crée une requête pour un genre d'entité particulier.

Une valeur "kind" vide correspond au renvoi de toutes les entités, y compris celles créées et gérées par d'autres fonctionnalités d'App Engine. Cela s'appelle une requête sans genre. Les requêtes sans genre ne peuvent pas inclure de filtres ni d'ordres de tri sur les valeurs de propriété.

func (*Query) Ancestor 

func (q *Query) Ancestor(ancestor *Key) *Query

La fonction Ancestor affiche une requête dérivée avec un filtre d'ancêtre. La valeur d'"ancestor" ne doit pas être "nil".

Func (*Query) BatchSize 

func (q *Query) BatchSize(size int) *Query

BatchSize affiche une requête dérivée pour récupérer le nombre de résultats fourni en même temps. Cette valeur doit être supérieure à zéro et égale ou inférieure à la limite.

func (*Query) Count

func (q *Query) Count(c context.Context) (int, error)

La fonction Count affiche le nombre de résultats de la requête.

La durée d'exécution et le nombre d'appels d'API effectués par la fonction Count évoluent de manière linéaire avec la somme du décalage et de la limite de la requête. Sauf dans le cas où vous attendez un faible nombre de résultats, il est préférable de spécifier une limite. Dans le cas contraire, la fonction continue jusqu'à ce qu'elle ait fini de compter ou que le contexte fourni expire.

func (*Query) Distinct 

func (q *Query) Distinct() *Query

La fonction Distinct affiche une requête dérivée qui génère des entités dédupliquées par rapport à l'ensemble des champs projetés. Elle n'est utilisée que pour les requêtes de projection. L'utilisation de Distinct ne peut pas être utilisée avec DistinctOn.

Func (*Query) DistinctOn 

func (q *Query) DistinctOn(fieldNames string) *Query

La fonction DistinctOn renvoie une requête dérivée qui génère des entités dédupliquées par rapport à l'ensemble des champs spécifiés. Elle n'est utilisée que pour les requêtes de projection. La liste de champs doit être un sous-ensemble de la liste des champs projetés. DistinctOn ne peut pas être utilisé avec Distinct.

func (*Query) End

func (q *Query) End(c Cursor) *Query

La fonction End affiche une requête dérivée avec le point de fin donné.

func (*Query) EventualConsistency 

func (q *Query) EventualConsistency() *Query

La fonction EventualConsistency affiche une requête dérivée qui renvoie des résultats cohérents à terme. Cela n'a d'effet que sur les requêtes ascendantes.

func (*Query) Filter 

func (q *Query) Filter(filterStr string, value interface{}) *Query

La fonction Filter affiche une requête dérivée avec un filtre basé sur des champs. L'argument filterStr doit être un nom de champ suivi d'un espace facultatif, suivi d'un opérateur, parmi les suivants : ">", "<", ">=", "<=" ou "=". Les champs sont comparés à la valeur fournie en utilisant l'opérateur. Lorsqu'il y a plusieurs filtres, ils sont reliés par un opérateur AND.

func (*Query) GetAll 

func (q *Query) GetAll(c context.Context, dst interface{}) ([]*Key, error)

La fonction GetAll exécute la requête dans le contexte donné et affiche toutes les clés correspondant à cette requête. Elle ajoute également les valeurs à "dst".

"dst" doit présenter le type []S, *[]S ou "*[]P", pour des types de structure "S" ou pour des types "P" autre qu'un pointeur et qu'une interface, tel que "P" ou "*P" mette en œuvre "PropertyLoadSaver".

En tant que cas particulier, le type "*PropertyList" est non valide pour "dst", même si "PropertyList" est une tranche de structure. Il est considéré comme non valide pour éviter d'être transmis par erreur lorsque "*[]PropertyList" est souhaité.

Les clés affichées par la fonction GetAll font l'objet d'une correspondance 1-1 avec les entités ajoutées à "dst".

Si "q" est une requête "ne contenant que des clés", la fonction GetAll ignore "dst" et n'affiche que les clés.

La durée d'exécution et le nombre d'appels d'API effectués par la fonction GetAll évoluent de manière linéaire avec la somme du décalage et de la limite de la requête. Sauf dans le cas où vous attendez un faible nombre de résultats, il est préférable de spécifier une limite. Dans le cas contraire, la méthode continue jusqu'à ce qu'elle ait fini de collecter des résultats ou que le contexte fourni expire.

func (*Query) KeysOnly 

func (q *Query) KeysOnly() *Query

La fonction KeysOnly affiche une requête dérivée qui ne produit que des clés, et non des clés et des entités. Elle ne peut pas être utilisée avec des requêtes de projection.

func (*Query) Limit 

func (q *Query) Limit(limit int) *Query

La fonction Limit affiche une requête dérivée qui limite le nombre de résultats renvoyés. Une valeur négative correspond à un nombre illimité.

func (*Query) Offset 

func (q *Query) Offset(offset int) *Query

La fonction Offset affiche une requête dérivée présentant un décalage du nombre de clés à passer avant de renvoyer les résultats. Une valeur négative n'est pas valide.

func (*Query) Order 

func (q *Query) Order(fieldName string) *Query

La fonction Order affiche une requête dérivée avec un ordre de tri basé sur des champs. Le tri s'effectue en respectant l'ordre dans lequel les éléments sont ajoutés. L'ordre croissant est défini par défaut. Pour trier dans l'ordre décroissant, "fieldName" doit être précédé d'un signe moins (-).

func (*Query) Project 

func (q *Query) Project(fieldNames string) *Query

La fonction Project affiche une requête dérivée qui ne génère que les champs donnés. Elle ne peut pas être utilisée avec la fonction KeysOnly.

func (*Query) Run 

func (q *Query) Run(c context.Context) *Iterator

La fonction Run exécute la requête dans le contexte donné.

func (*Query) Start 

func (q *Query) Start(c Cursor) *Query

La fonction Start affiche une requête dérivée avec le point de départ donné.

TransactionOptions

type TransactionOptions struct {
	// XG is whether the transaction can cross multiple entity groups. In
	// comparison, a single group transaction is one where all datastore keys
	// used have the same root key. Note that cross group transactions do not
	// have the same behavior as single group transactions. In particular, it
	// is much more likely to see partially applied transactions in different
	// entity groups, in global queries.
	// It is valid to set XG to true even if the transaction is within a
	// single entity group.
	XG bool
	// Attempts controls the number of retries to perform when commits fail
	// due to a conflicting transaction. If omitted, it defaults to 3.
	Attempts int
	// ReadOnly controls whether the transaction is a read only transaction.
	// Read only transactions are potentially more efficient.
	ReadOnly bool
}

Le type TransactionOptions correspond aux options d'exécution d'une transaction.