L'API Google Drive vous permet d'importer des données de fichier lorsque vous créez ou mettez à jour un File
. Pour en savoir plus sur la création d'un fichier ne contenant que des métadonnées, tel qu'un dossier, consultez la section Créer des fichiers ne contenant que des métadonnées.
Vous pouvez effectuer trois types d'importation:
Importation simple (
uploadType=media
): utilisez ce type d'importation pour transférer un petit fichier multimédia (5 Mo maximum) sans fournir de métadonnées. Pour effectuer une importation simple, consultez la section Effectuer une importation simple.Importation en plusieurs parties (
uploadType=multipart
): "Utilisez ce type d'importation pour transférer un petit fichier (5 Mo ou moins), ainsi que les métadonnées qui le décrivent, dans une seule requête. Pour effectuer une importation en plusieurs parties, consultez la section Effectuer une importation en plusieurs parties.Importation avec reprise (
uploadType=resumable
): utilisez ce type d'importation pour les fichiers volumineux (supérieurs à 5 Mo) et en cas de risque d'interruption du réseau, par exemple lors de la création d'un fichier à partir d'une application mobile. Les importations avec reprise sont également un bon choix pour la plupart des applications, car elles fonctionnent également pour les petits fichiers à un coût minimal d'une requête HTTP supplémentaire par importation. Pour effectuer une importation avec reprise, consultez la section Effectuer une importation avec reprise.
Les bibliothèques clientes des API Google implémentent au moins l'un de ces types d'importations. Reportez-vous à la documentation des bibliothèques clientes pour en savoir plus sur l'utilisation de chacun de ces types.
Utiliser PATCH
plutôt que PUT
Pour rappel, le verbe HTTP PATCH
permet une mise à jour partielle des ressources de fichier, tandis que le verbe HTTP PUT
permet le remplacement complet des ressources. Notez que PUT
peut introduire des modifications destructives lors de l'ajout d'un nouveau champ à une ressource existante.
Lorsque vous importez une ressource de fichier, suivez les consignes ci-dessous:
- Utilisez le verbe HTTP documenté dans la documentation de référence de l'API pour la requête initiale d'une importation avec reprise ou pour la seule requête d'une importation simple ou en plusieurs parties.
- Utilisez
PUT
pour toutes les requêtes ultérieures d'importation avec reprise une fois la requête lancée. Ces requêtes importent du contenu, quelle que soit la méthode appelée.
Effectuer une importation simple
Pour effectuer une importation simple, utilisez la méthode files.create
avec uploadType=media
.
Pour effectuer une importation simple, procédez comme suit:
HTTP
Créez une requête
POST
dans l'URI /upload de la méthode avec le paramètre de requêteuploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Ajoutez les données du fichier au corps de la requête.
Ajoutez les en-têtes HTTP suivants:
Content-Type
: indiquez le type de média MIME de l'objet en cours d'importation.Content-Length
: indiquez le nombre d'octets importés. Si vous utilisez l'encodage de transfert fragmenté, cet en-tête n'est pas obligatoire.
Envoyez la requête. Si la requête aboutit, le serveur renvoie le code d'état
HTTP 200 OK
avec les métadonnées du fichier. {HTTP}
Lorsque vous effectuez une importation simple, des métadonnées de base sont créées et certains attributs sont déduits du fichier, tels que le type MIME ou modifiedTime
. Vous pouvez utiliser une importation simple si vous avez de petits fichiers et que les métadonnées de fichiers ne sont pas importantes.
Effectuer une importation en plusieurs parties
Une requête d'importation en plusieurs parties vous permet d'importer des métadonnées et des données dans la même requête. Utilisez cette option si les données que vous envoyez sont suffisamment petites pour être réimportées dans leur intégralité en cas d'échec de la connexion.
Pour effectuer une importation en plusieurs parties, utilisez la méthode files.create
avec uploadType=multipart
.
L'exemple suivant montre comment effectuer une importation en plusieurs parties:
Java
Python
Node.js
PHP
.NET
HTTP
Créez une requête
POST
dans l'URI /upload de la méthode avec le paramètre de requêteuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Créez le corps de la requête. Mettez en forme le corps en fonction du type de contenu "multipart/related" RFC 2387, qui contient deux parties:
- Métadonnées. Les métadonnées doivent apparaître en premier et comporter un en-tête
Content-Type
défini surapplication/json;
charset=UTF-8
. Ajoutez les métadonnées du fichier au format JSON. - Médias. Le média doit venir en second et comporter un en-tête
Content-Type
de n'importe quel type MIME. Ajoutez les données du fichier à la partie multimédia.
Identifiez chaque partie par une chaîne de délimitation, précédée de deux traits d'union. En outre, ajoutez deux traits d'union après la dernière chaîne de délimitation.
- Métadonnées. Les métadonnées doivent apparaître en premier et comporter un en-tête
Ajoutez ces en-têtes HTTP de premier niveau:
Content-Type
: définissez la valeur surmultipart/related
et incluez la chaîne de limite que vous utilisez pour identifier les différentes parties de la requête. Exemple:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Défini sur le nombre total d'octets dans le corps de la requête.
Envoyez la requête.
Pour créer ou mettre à jour la partie métadonnées uniquement, sans les données associées, envoyez une requête POST
ou PATCH
au point de terminaison de la ressource standard : https://www.googleapis.com/drive/v3/files
Si la requête aboutit, le serveur renvoie le code d'état HTTP 200 OK
avec les métadonnées du fichier.
Lors de la création de fichiers, ils doivent spécifier une extension dans le champ name
du fichier. Par exemple, lorsque vous créez un fichier photo JPEG, vous pouvez spécifier un élément comme "name": "photo.jpg"
dans les métadonnées. Les appels suivants à files.get
renvoient la propriété fileExtension
en lecture seule contenant l'extension initialement spécifiée dans le champ name
.
Effectuer une importation avec reprise
Une importation avec reprise vous permet de reprendre une opération d'importation après un échec de communication ayant interrompu le flux de données. Étant donné qu'il n'est pas nécessaire de redémarrer les importations de fichiers volumineux dès le départ, les importations avec reprise peuvent également réduire l'utilisation de la bande passante en cas de défaillance du réseau.
Les importations avec reprise sont utiles lorsque la taille de vos fichiers peut varier considérablement ou lorsqu'il existe une limite de temps fixe pour les requêtes (par exemple, les tâches en arrière-plan de l'OS mobile et certaines requêtes App Engine). Vous pouvez également utiliser des importations avec reprise dans les cas où vous souhaitez afficher une barre de progression de l'importation.
Une importation avec reprise comprend plusieurs étapes générales:
- Envoyez la requête initiale et récupérez l'URI de la session avec reprise.
- Importez les données et surveillez l'état de l'importation.
- (Facultatif) Si l'importation est interrompue, reprenez l'importation.
Envoyer la requête initiale
Pour lancer une importation avec reprise, utilisez la méthode files.create
avec uploadType=resumable
.
HTTP
Créez une requête
POST
dans l'URI /upload de la méthode avec le paramètre de requêteuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Si la requête de lancement aboutit, la réponse inclut un code d'état HTTP
200 OK
. En outre, il inclut un en-têteLocation
qui spécifie l'URI de la session avec reprise:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Enregistrez l'URI de la session avec reprise afin de pouvoir importer les données du fichier et interroger l'état de l'importation. L'URI d'une session avec reprise expire au bout d'une semaine.
Si vous disposez de métadonnées pour le fichier, ajoutez-les au corps de la requête au format JSON. Sinon, laissez le corps de la requête vide.
Ajoutez les en-têtes HTTP suivants:
X-Upload-Content-Type
Facultatif. Défini sur le type MIME des données du fichier à transférer dans les requêtes ultérieures. Si le type MIME des données n'est pas spécifié dans les métadonnées ou via cet en-tête, l'objet est diffusé en tant queapplication/octet-stream.
.X-Upload-Content-Length
Facultatif. Défini sur le nombre d'octets de données de fichier à transférer dans les requêtes ultérieures.Content-Type
. Obligatoire si vous disposez de métadonnées pour le fichier. Défini surapplication/json;
charset=UTF-8
.Content-Length
. Obligatoire, sauf si vous utilisez l'encodage de transfert fragmenté. Définissez le nombre d'octets dans le corps de cette requête initiale.
Envoyez la requête. Si la requête de lancement de session aboutit, la réponse inclut un code d'état
200 OK HTTP
. En outre, la réponse inclut un en-têteLocation
qui spécifie l'URI de la session avec reprise. Utilisez l'URI de la session avec reprise pour importer les données du fichier et interroger l'état de l'importation. L'URI d'une session avec reprise expire au bout d'une semaine.Copiez et enregistrez l'URL de la session avec reprise.
Passez à la section Importer le contenu.
Importer le contenu
Il existe deux façons d'importer un fichier dans le cadre d'une session avec reprise :
- Importer du contenu dans une seule requête: utilisez cette approche lorsque le fichier peut être importé en une seule requête, s'il n'y a pas de limite de temps fixe pour une seule requête ou si vous n'avez pas besoin d'afficher un indicateur de progression de l'importation. Cette approche est préférable, car elle nécessite moins de requêtes et améliore les performances.
Importez le contenu en plusieurs fragments: utilisez cette approche si vous devez réduire la quantité de données transférées dans une seule requête. Vous devrez peut-être réduire les données transférées lorsqu'il existe une limite de temps fixe pour les requêtes individuelles, comme cela peut être le cas pour certaines classes de requêtes App Engine. Cette approche est également utile si vous devez fournir un indicateur personnalisé pour indiquer la progression de l'importation.
HTTP – requête unique
- Créez une requête
PUT
vers l'URI de la session avec reprise. - Ajoutez les données du fichier au corps de la requête.
- Ajoutez un en-tête HTTP Content-Length, défini sur le nombre d'octets du fichier.
- Envoyez la requête. Si la requête d'importation est interrompue ou si vous recevez une réponse
5xx
, suivez la procédure décrite dans Reprendre une importation interrompue.
HTTP – Requêtes multiples
Créez une requête
PUT
vers l'URI de la session avec reprise.Ajoutez les données du fragment au corps de la requête. Créez des fragments par multiples de 256 Ko (256 x 1 024 octets), à l'exception du fragment final qui termine l'importation. La taille des fragments doit être aussi grande que possible pour que l'importation soit efficace.
Ajoutez les en-têtes HTTP suivants:
Content-Length
. Défini sur le nombre d'octets du fragment actuel.Content-Range
. Indiquez les octets du fichier que vous importez. Par exemple,Content-Range: bytes 0-524287/2000000
indique que vous importez les 524 288 premiers octets (256 x 1 024 x 2) dans un fichier de 2 000 000 octets.
Envoyez la requête, puis traitez la réponse. Si la requête d'importation est interrompue ou si vous recevez une réponse
5xx
, suivez la procédure décrite dans Reprendre une importation interrompue.Répétez les étapes 1 à 4 pour chaque fragment restant dans le fichier. Utilisez l'en-tête
Range
dans la réponse pour déterminer où démarrer le prochain fragment. Ne partez pas du principe que le serveur a reçu tous les octets envoyés dans la requête précédente.
Une fois l'importation complète du fichier terminée, vous recevez une réponse 200 OK
ou 201 Created
, ainsi que toutes les métadonnées associées à la ressource.
Reprendre une importation interrompue
Si une requête d'importation se termine avant une réponse ou si vous recevez une réponse 503
Service Unavailable
, vous devez reprendre l'importation interrompue.
HTTP
Pour demander l'état de l'importation, créez une requête
PUT
vide à destination de l'URI de la session avec reprise.Ajoutez un en-tête
Content-Range
pour indiquer que la position actuelle dans le fichier est inconnue. Par exemple, définissezContent-Range
sur*/2000000
si la longueur totale de votre fichier est de 2 000 000 octets. Si vous ne connaissez pas la taille totale du fichier, définissezContent-Range
sur*/*
.Envoyez la requête.
Traitez la réponse:
- Une réponse
200 OK
ou201 Created
indique que l'importation a été effectuée et qu'aucune autre action n'est requise. - Une réponse
308 Resume Incomplete
indique que vous devez continuer à importer le fichier. - Une réponse
404 Not Found
indique que la session d'importation a expiré et que l'importation doit redémarrer depuis le début.
- Une réponse
Si vous avez reçu une réponse
308 Resume Incomplete
, traitez l'en-têteRange
de la réponse pour déterminer les octets reçus par le serveur. Si la réponse ne comporte pas d'en-têteRange
, aucun octet n'a été reçu. Par exemple, un en-têteRange
debytes=0-42
indique que les 43 premiers octets du fichier ont été reçus et que le prochain fragment à importer commencera par l'octet 44.Maintenant que vous savez où reprendre l'importation, poursuivez l'importation du fichier en commençant par l'octet suivant. Incluez un en-tête
Content-Range
pour indiquer la partie du fichier que vous envoyez. Par exemple,Content-Range: bytes 43-1999999
indique que vous envoyez les octets 44 à 2 000 000.
Gérer les erreurs d'importation de contenus multimédias
Lorsque vous importez des contenus multimédias, suivez ces bonnes pratiques pour gérer les erreurs:
- Pour les erreurs
5xx
, reprenez ou relancez les importations qui échouent en raison d'interruptions de connexion. Pour en savoir plus sur la gestion des erreurs5xx
, consultez la page Erreurs 500, 502, 503, 504. - Pour les erreurs
403 rate limit
, relancez l'importation. Pour en savoir plus sur la gestion des erreurs403 rate limit
, consultez la section Erreur 403 :rateLimitExceeded
. - Pour toute erreur
4xx
(y compris403
) lors d'une importation avec reprise, redémarrez l'importation. Ces erreurs indiquent que la session d'importation a expiré et doit être redémarrée en demandant un nouvel URI de session. Les sessions d'importation expirent également après une semaine d'inactivité.
Importer dans des types Google Docs
Lorsque vous créez un fichier dans Drive, vous pouvez le convertir dans un type de fichier Google Workspace, tel que Google Docs ou Sheets. Par exemple, vous souhaitez peut-être transformer un document de votre outil de traitement de texte préféré en document Docs pour profiter de ses fonctionnalités.
Pour convertir un fichier dans un type de fichier Google Workspace spécifique, spécifiez l'mimeType
Google Workspace lors de sa création.
L'exemple suivant montre comment convertir un fichier CSV en feuille Google Workspace:
Java
Python
Node.js
PHP
.NET
Pour savoir si une conversion est disponible, vérifiez le tableau importFormats
de la ressource about
avant de créer le fichier.
Les conversions acceptées sont disponibles dynamiquement dans ce tableau. Voici quelques formats d'importation courants:
De | À |
---|---|
Microsoft Word, OpenDocument Text, HTML, RTF, texte brut | Google Docs |
Microsoft Excel, feuille de calcul OpenDocument, CSV, TSV, texte brut | Google Sheets |
Microsoft PowerPoint, présentation OpenDocument | Google Slides |
JPEG, PNG, GIF, BMP, PDF | Google Docs (intègre l'image dans un document) |
Texte brut (type MIME spécial), JSON | Google Apps Script |
Lorsque vous importez et convertissez un contenu multimédia lors d'une requête update
vers un fichier Docs, Sheets ou Slides, l'intégralité du contenu du document est remplacé.
Lorsque vous convertissez une image au format Docs, Drive utilise la reconnaissance optique des caractères (OCR) pour convertir l'image en texte. Vous pouvez améliorer la qualité de l'algorithme de reconnaissance optique des caractères en spécifiant le code de langue BCP 47 applicable dans le paramètre ocrLanguage
. Le texte extrait apparaît dans le document à côté de l'image intégrée.
Utilisez un ID prégénéré pour importer des fichiers
L'API Drive vous permet de récupérer une liste d'ID de fichiers prégénérés utilisés pour importer et créer des ressources. Les requêtes d'importation et de création de fichiers peuvent utiliser ces ID prégénérés. Définissez le champ id
dans les métadonnées du fichier.
Pour créer des ID prégénérés, appelez files.generateIds
avec le nombre d'ID à créer.
Vous pouvez effectuer de nouvelles tentatives d'importation avec des ID pré-générés en toute sécurité en cas d'erreur de serveur ou de délai d'inactivité indéterminés. Si le fichier a bien été créé, les tentatives suivantes renvoient une erreur HTTP 409
et ne créent pas de fichiers en double.
Définir le texte indexable pour les types de fichiers inconnus
Les utilisateurs peuvent rechercher le contenu d'un document à l'aide de l'interface utilisateur de Drive. Vous pouvez également utiliser files.list
et le champ fullText
pour rechercher du contenu depuis votre application. Pour en savoir plus, consultez Rechercher des fichiers et des dossiers.
Drive indexe automatiquement les documents pour la recherche lorsqu'il reconnaît le type de fichier, y compris les documents texte, les PDF, les images contenant du texte et d'autres types courants. Si votre application enregistre d'autres types de fichiers (tels que des dessins, des vidéos et des raccourcis), vous pouvez améliorer la visibilité en fournissant du texte indexable dans le champ contentHints.indexableText
du fichier.
Pour en savoir plus sur le texte indexable, consultez Gérer les métadonnées de fichiers.