Présentation de l'API Blobstore pour les anciens services groupés

Remarque : Nous vous recommandons d'utiliser Cloud Storage plutôt que Blobstore pour stocker les données des blobs.

L'API Blobstore permet à votre application de diffuser des objets de données, appelés objets blob, beaucoup plus volumineux que la taille autorisée pour les objets dans le service Datastore. Les objets blob sont particulièrement utiles pour la diffusion de fichiers de grande taille, tels que des fichiers vidéo ou image, ainsi que pour le transfert de fichiers de données volumineux. Les objets blob sont générés lors du transfert d'un fichier via une requête HTTP. Pour ce faire, vos applications présentent généralement à l'utilisateur un formulaire avec un champ de téléchargement de fichier. Une fois ce formulaire envoyé, le Blobstore crée un objet blob à partir du contenu du fichier et renvoie une référence opaque à l'objet blob, appelée clé blob, que vous pouvez ensuite utiliser pour diffuser l'objet blob. L'application peut diffuser la valeur complète du blob en réponse à une demande d'utilisateur. Elle peut aussi lire directement la valeur à l'aide d'une interface de type fichier en streaming.

Présentation du Blobstore

Google App Engine inclut le service Blobstore, qui permet aux applications de diffuser des objets de données limités uniquement par la quantité de données pouvant être importées ou téléchargées via une seule connexion HTTP. Ces objets sont appelés valeurs Blobstore ou objets blob. Les valeurs Blobstore sont diffusées en tant que réponses par des gestionnaires de requêtes et créées en tant que transferts via des formulaires Web. Les applications ne créent pas directement de données blob. En effet, les objets blob sont créés indirectement, par un formulaire Web envoyé ou par une autre demande HTTP POST. Les valeurs de Blobstore peuvent être diffusées vers l'utilisateur et sont accessibles par l'application dans un flux de type fichier, à l'aide de l'API Blobstore.

Remarque : Les blobs, tels que définis par le service Blobstore, ne sont pas liés aux valeurs des propriétés de blob utilisées par le datastore.

Pour inviter un utilisateur à importer une valeur Blobstore, votre application présente un formulaire Web avec un champ d'importation de fichier. L'application génère l'URL d'action du formulaire en appelant l'API Blobstore. Le navigateur de l'utilisateur importe le fichier directement dans le Blobstore via l'URL générée. Blobstore stocke ensuite l'objet blob, réécrit la requête de manière à inclure la clé blob et la transmet à un chemin d'accès dans votre application. Un gestionnaire de demandes situé sur ce chemin dans votre application peut alors procéder au traitement approfondi du formulaire.

Pour diffuser un objet blob, votre application définit un en-tête sur la réponse sortante et App Engine remplace la réponse par la valeur de l'objet blob.

Une fois créés, les objets blob ne peuvent pas être modifiés. Cependant, ils peuvent être supprimés. Chaque objet blob est associé à un enregistrement d'informations, stocké dans le datastore. Cet enregistrement fournit des détails, tels que la date de création et le type de contenu de cet objet blob. Vous pouvez utiliser la clé blob pour récupérer des enregistrements d'informations relatifs aux objets blob et interroger leurs propriétés.

Utiliser le service Blobstore

Les applications peuvent utiliser le Blobstore pour accepter l'importation des fichiers volumineux par les utilisateurs et pour diffuser ces fichiers. Une fois importés, ces fichiers sont appelés blobs. Les applications n'accèdent pas directement aux blobs grâce à leur nom de fichier. Elles ont plutôt recours au type appengine.BlobKey.

L'utilisateur crée un objet blob en soumettant un formulaire HTML qui inclut un ou plusieurs champs de saisie de fichiers. Votre application définit blobstore.UploadURL comme destination (action) de ce formulaire, en transmettant à la fonction le chemin d’URL d’un gestionnaire dans votre application. Lorsque l'utilisateur envoie le formulaire, son navigateur transfère directement les fichiers indiqués au service Blobstore. Le service Blobstore réécrit la requête de l'utilisateur et stocke les fichiers transférés, en les remplaçant par une ou plusieurs clés blob correspondantes. Il transmet ensuite la requête ainsi modifiée au gestionnaire à l'adresse URL que vous avez fournie à la fonction blobstore.UploadURL. Ce gestionnaire peut procéder à un traitement supplémentaire en fonction de la clé blob. Finalement, le gestionnaire doit renvoyer une réponse de redirection à en-têtes uniquement (301, 302 ou 303). En règle générale, un navigateur vous redirige vers une autre page indiquant l'état de l'importation du blob.

L'application peut lire les parties d'une valeur Blobstore à l'aide d'un objet blobstore.Reader.

Importer un blob

Pour créer et importer un objet blob, suivez la procédure suivante :

1. Créez une URL d'importation

Appelez blobstore.UploadURL pour créer une URL d'importation pour le formulaire destiné à l'utilisateur, en transmettant le chemin d'accès de l'application à charger lorsque la requête POST du formulaire est terminée.

ctx := appengine.NewContext(r)
uploadURL, err := blobstore.UploadURL(ctx, "/upload", nil)
if err != nil {
	serveError(ctx, w, err)
	return
}

2. Créez un formulaire d'importation

Le formulaire doit inclure un champ d'importation de fichiers et le enctype du formulaire doit être défini sur multipart/form-data. Lorsque l'utilisateur envoie le formulaire, la requête POST est traitée par l'API Blobstore, ce qui entraîne la création de l'objet blob. L'API crée également un enregistrement d'informations pour le blob et le stocke dans le datastore. Elle transmet ensuite la requête réécrite à votre application au chemin fourni en tant que clé blob.

	var rootTemplate = template.Must(template.New("root").Parse(rootTemplateHTML))

	const rootTemplateHTML = `
<html><body>
<form action="{{.}}" method="POST" enctype="multipart/form-data">
Upload File: <input type="file" name="file"><br>
<input type="submit" name="submit" value="Submit">
</form></body></html>
`

Remarque : Vous devez diffuser la page du formulaire avec un Content-Type défini sur text/html; charset=utf-8, sinon les noms de fichiers contenant des caractères non-ASCII ne seront pas interprétés correctement.
Il s'agit du type de contenu par défaut dans l'environnement Go, mais n'oubliez pas de le faire si vous définissez votre propre Content-Type.

3. Implémentez le gestionnaire d'importation

Dans ce gestionnaire, vous pouvez stocker la clé blob avec le reste du modèle de données de l'application. La clé blob elle-même reste accessible à partir de l'entité d'informations relatives à l'objet blob dans le datastore. Notez qu'une fois que l'utilisateur a soumis le formulaire et que votre gestionnaire a été appelé, l'objet blob a déjà été sauvegardé et les informations associées ajoutées au datastore. Si votre application ne souhaite pas conserver l'objet blob, vous devez le supprimer immédiatement pour éviter qu'il ne devienne orphelin :

ctx := appengine.NewContext(r)
blobs, _, err := blobstore.ParseUpload(r)
if err != nil {
	serveError(ctx, w, err)
	return
}
file := blobs["file"]
if len(file) == 0 {
	log.Errorf(ctx, "no file uploaded")
	http.Redirect(w, r, "/", http.StatusFound)
	return
}
http.Redirect(w, r, "/serve/?blobKey="+string(file[0].BlobKey), http.StatusFound)

Lorsque le service Blobstore réécrit la requête utilisateur, le corps des parties MIME des fichiers importés est vidé, et la clé blob est ajoutée en tant qu'en-tête de la partie MIME. Tous les autres champs et parties du formulaire sont préservés et transmis au gestionnaire de transferts. Si vous ne spécifiez pas de type de contenu, le Blobstore tentera de l'inférer à partir de l'extension du fichier. Si cela n'est pas possible, le type de contenu application/octet-stream est affecté à l'objet blob nouvellement créé.

Diffuser un blob

Pour diffuser des blobs, vous devez inclure un gestionnaire de téléchargement de blob en tant que chemin d'accès dans votre application. Ce gestionnaire transmet la clé blob correspondant à l'objet spécifié à blobstore.Send. Dans cet exemple, la clé blob est transmise au gestionnaire de téléchargement en tant qu'argument URL r.FormValue("blobKey"). Dans la pratique, le gestionnaire de téléchargement peut obtenir la clé blob par n'importe quel moyen de votre choix, par exemple via une autre méthode ou action utilisateur.

blobstore.Send(w, appengine.BlobKey(r.FormValue("blobKey")))

Les blobs peuvent être diffusés à partir de n'importe quelle URL d'application. Pour diffuser un blob dans votre application, vous devez mettre un en-tête spécial dans la réponse contenant la clé blob. App Engine remplace le corps de la réponse par le contenu de l'objet blob.

Plages d'octets des objets blob

Le Blobstore permet de diffuser uniquement une partie d'une grande valeur, plutôt que la totalité de cette valeur, en réponse à une requête. Pour diffuser une valeur partielle, l'en-tête X-AppEngine-BlobRange doit être inclus dans la réponse sortante. Sa valeur correspond à une plage d'octets HTTP standard. La numérotation des octets est basée sur zéro. Un champ X-AppEngine-BlobRange vide indique à l'API d'ignorer l'en-tête de plage et de diffuser l'objet blob dans son intégralité. Exemples de plages :

• 0-499 : diffuse les 500 premiers octets de la valeur (octets 0 à 499 inclus).
• 500-999 : diffuse 500 octets à partir du 501e octet.
• 500- : diffuse tous les octets à partir du 501e octet, jusqu'à la fin de la valeur.
• -500 : diffuse les 500 derniers octets de la valeur.

Si la plage d'octets est valide pour la valeur Blobstore, le Blobstore envoie au client un code d'état 206 Partial Content ainsi que la plage d'octets requise. Si la plage n'est pas valide pour la valeur, le Blobstore envoie 416 Requested Range Not Satisfiable.

Le Blobstore n'accepte pas plusieurs plages d'octets dans une même requête (par exemple, 100-199,200-299), qu'elles se chevauchent ou non.

Exemple d'application complète

Dans l'exemple d'application suivant, l'URL principale de l'application charge le formulaire qui demande un fichier à importer à l'utilisateur, et le gestionnaire d'importation appelle immédiatement le gestionnaire de téléchargement pour diffuser les données. Cela permet de simplifier l'exemple d'application. En pratique, il est peu probable que vous utilisiez l'URL principale pour demander un transfert de données, ou encore que vous diffusiez un objet blob immédiatement après l'avoir transféré.

package blobstore_example

import (
	"context"
	"html/template"
	"io"
	"net/http"

	"google.golang.org/appengine"
	"google.golang.org/appengine/blobstore"
	"google.golang.org/appengine/log"
)

func serveError(ctx context.Context, w http.ResponseWriter, err error) {
	w.WriteHeader(http.StatusInternalServerError)
	w.Header().Set("Content-Type", "text/plain")
	io.WriteString(w, "Internal Server Error")
	log.Errorf(ctx, "%v", err)
}

var rootTemplate = template.Must(template.New("root").Parse(rootTemplateHTML))

const rootTemplateHTML = `
<html><body>
<form action="{{.}}" method="POST" enctype="multipart/form-data">
Upload File: <input type="file" name="file"><br>
<input type="submit" name="submit" value="Submit">
</form></body></html>
`

func handleRoot(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)
	uploadURL, err := blobstore.UploadURL(ctx, "/upload", nil)
	if err != nil {
		serveError(ctx, w, err)
		return
	}
	w.Header().Set("Content-Type", "text/html")
	err = rootTemplate.Execute(w, uploadURL)
	if err != nil {
		log.Errorf(ctx, "%v", err)
	}
}

func handleServe(w http.ResponseWriter, r *http.Request) {
	blobstore.Send(w, appengine.BlobKey(r.FormValue("blobKey")))
}

func handleUpload(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)
	blobs, _, err := blobstore.ParseUpload(r)
	if err != nil {
		serveError(ctx, w, err)
		return
	}
	file := blobs["file"]
	if len(file) == 0 {
		log.Errorf(ctx, "no file uploaded")
		http.Redirect(w, r, "/", http.StatusFound)
		return
	}
	http.Redirect(w, r, "/serve/?blobKey="+string(file[0].BlobKey), http.StatusFound)
}

func init() {
	http.HandleFunc("/", handleRoot)
	http.HandleFunc("/serve/", handleServe)
	http.HandleFunc("/upload", handleUpload)
}

Utiliser l'API Blobstore avec Google Cloud Storage

Vous pouvez exploiter l'API Blobstore pour stocker des blobs dans Cloud Storage plutôt que dans Blobstore. Vous devez alors configurer un bucket, comme décrit dans la documentation de Google Cloud Storage, et spécifier le bucket et le nom du fichier dans l'objet UploadURLOptions que vous fournissez à la fonction UploadURL. Dans votre gestionnaire d'importation, vous devez traiter la carte des blobs renvoyés et stocker explicitement le nom de fichier Google Cloud Storage nécessaire à la récupération ultérieure du blob.

Vous pouvez également diffuser des objets Cloud Storage à l'aide de l'API Blobstore. Pour diffuser un objet Cloud Storage, générez l'objet blobkey requis à l'aide de BlobKeyForFile, comme décrit à la section Diffuser un blob.

Quotas et limites

L'espace utilisé pour les valeurs Blobstore est décompté dans le quota Stored Data (billable) (Données stockées (facturables)). Les entités d'informations d'objets blob du datastore sont comptabilisées dans les limites associées au datastore. Notez que Google Cloud Storage est un service payant. Vous serez facturé conformément à la grille tarifaire de Cloud Storage.

Pour en savoir plus sur les quotas de sécurité à l'échelle du système, consultez la rubrique Quotas.

Outre les quotas de sécurité à l'échelle du système, les limites suivantes s'appliquent spécifiquement à l'utilisation du Blobstore :

• La taille maximale des données Blobstore lisibles par l'application avec un seul appel d'API est de 32 mégaoctets.
• Le nombre maximal de fichiers importables dans un seul formulaire POST est de 500.

Pour en savoir plus sur ces limites de taille, consultez la documentation de la fonction Send.