L'API Google Drive vous permet d'importer des données lorsque vous créez ou mettez à jour un
File
Pour savoir comment créer un
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'importations:
Importation simple (
uploadType=media
): utilisez ce type d'importation pour transférer un de petite taille (5 Mo ou moins) sans fournir de métadonnées. Pour effectuer une pour une importation simple, consultez l'article 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) accompagné des métadonnées qui décrivent en 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 forte probabilité de connexion sans interruption, par exemple lors de la création d'un fichier à partir d'une application mobile. Réactivable sont également un bon choix pour la plupart des applications, car elles fonctionnent aussi pour les petits fichiers pour un coût minimal d'une requête HTTP supplémentaire par importation. Pour effectuer une importation avec reprise, consultez Effectuer une importation avec reprise. importer.
Les bibliothèques clientes des API Google mettent en œuvre au moins l'un de ces types de mises en ligne. Reportez-vous à la bibliothèque cliente pour découvrir comment utiliser chacun de ces types.
Utiliser PATCH
plutôt que PUT
Pour rappel, le verbe HTTP PATCH
permet de mettre à jour partiellement les ressources d'un fichier
tandis que le verbe HTTP PUT
prend en charge le remplacement complet des ressources. Notez que PUT
.
peut introduire des modifications importantes lors de l'ajout d'un champ à une ressource existante.
Lorsque vous importez une ressource de fichier, suivez les consignes ci-dessous:
- Utilisez le verbe HTTP indiqué dans la documentation de référence de l'API pour la requête initiale de une importation avec reprise ou pour la seule requête d'importation simple ou en plusieurs parties.
- Utilisez
PUT
pour toutes les requêtes suivantes pour une importation avec reprise une fois que le a démarré. Ces demandes concernent l'importation de contenu, méthode appelée.
Effectuer une importation simple
Pour effectuer une importation simple, utilisez la méthode
files.create
avec
uploadType=media
Voici comment effectuer une importation simple:
HTTP
Créez une requête
POST
vers l'URI /upload de la méthode avec la requête paramètre deuploadType=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
Défini sur le type de média MIME de l'objet en cours de traitement importées.Content-Length
Définissez le nombre d'octets que vous importez. Si vous utilisez encodage de transfert en bloc, 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 mise en ligne simple, des métadonnées de base sont créées et certains attributs
sont déduits du fichier, comme le type MIME ou modifiedTime
. Vous pouvez utiliser
une importation simple lorsque vous avez des fichiers de petite taille et que les métadonnées des 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 requête. Utilisez cette option si les données que vous envoyez sont suffisamment petites pour être réimportées, dans son 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
Voici comment effectuer une importation en plusieurs parties:
Java
Python
Node.js
PHP
.NET
HTTP
Créez une requête
POST
vers l'URI /upload de la méthode avec la requête paramètre deuploadType=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 de la manière suivante : type de contenu multipart/related RFC 2387, qui contient deux parties:
- Métadonnées. Les métadonnées doivent apparaître en premier et avoir un
Content-Type
en-tête défini surapplication/json;
charset=UTF-8
. Ajouter les métadonnées du fichier au format JSON. - Multimédia : Le contenu multimédia doit apparaître en deuxième position et doit avoir 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 à l'aide d'une chaîne de délimitation, précédée de deux traits d'union. Dans ajoutez deux traits d'union après la chaîne de délimitation finale.
- Métadonnées. Les métadonnées doivent apparaître en premier et avoir un
Ajoutez les en-têtes HTTP de premier niveau suivants:
Content-Type
Définir surmultipart/related
et inclure la limite que vous utilisez pour identifier les différentes parties de la requête. Pour 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
ainsi que le paramètre
de métadonnées.
Lors de la création des fichiers, ils doivent spécifier une extension dans la section name
du fichier.
. Par exemple, lors de la création d'un fichier photo JPEG, vous pouvez spécifier quelque chose
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 une communication une défaillance interrompt le flux de données. Comme vous n'avez pas besoin de redémarrer les importations de fichiers, les importations avec reprise peuvent aussi réduire en cas de panne du réseau.
Les importations avec reprise sont utiles lorsque la taille de vos fichiers peut varier considérablement ou Il existe une limite de temps fixe pour les requêtes (comme les tâches en arrière-plan du système d'exploitation mobile et certaines requêtes App Engine). Vous pouvez également utiliser des importations avec reprise lorsque 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 perturbée, reprenez-la.
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
vers l'URI /upload de la méthode avec la requête paramètre deuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Si la requête de lancement aboutit, la réponse inclut un
200 OK
Code d'état HTTP. De plus, 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 la mise en ligne. 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ée 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éfinissez le nombre d'octets de qui sont transférées dans les demandes ultérieures.Content-Type
. Obligatoire si vous disposez de métadonnées pour le fichier. Définir 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, inclut un code d'état
200 OK HTTP
. De plus, 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 le état de la mise en ligne. 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 en une seule requête: utilisez cette approche lorsque le fichier peut être importé en une seule demande, s'il n'y a pas de limite de temps fixe pour ou si vous n'avez pas besoin d'afficher d'indicateur de progression de l'importation. Ce est la meilleure approche, car elle nécessite moins de requêtes et permet des performances.
Importer le contenu en plusieurs fragments: utilisez cette approche si vous devez de réduire la quantité de données transférées dans une seule demande. Vous aurez peut-être besoin afin de réduire le volume de données transférées alors qu'il existe un délai fixe requêtes, 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é afficher 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 demande d'importation est interrompue ou si vous recevez une
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éer des fragments par multiples de 256 Ko (256 x 1 024 octets), à l'exception du fragment final qui se termine l'importation. La taille des fragments doit être la plus grande 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
Permet d'afficher les octets du fichier que vous importez. Pour exemple,Content-Range: bytes 0-524287/2000000
indique que vous importez le 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 demande d'importation est interrompu, ou si vous recevez une réponse
5xx
, suivez la procédure décrite dans Reprenez une importation interrompue.Répétez les étapes 1 à 4 pour chaque fragment qui reste dans le fichier. Utilisez les
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 du fichier terminée, vous recevez une notification de type 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 est interrompue avant que vous ne répondiez 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 fichier est inconnu. Par exemple, définissezContent-Range
sur*/2000000
si votre la longueur totale du 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 pour importer le fichier. - Une réponse
404 Not Found
indique que la session d'importation a expiré et l'importation doit être relancée depuis le début.
- Une réponse
Si vous avez reçu une réponse
308 Resume Incomplete
, traitez leRange
de la réponse pour déterminer les octets reçus par le serveur. Si le 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 la première 43 octets du fichier ont été reçus et que le prochain fragment à importer devrait commencer par l'octet 44.Maintenant que vous savez où reprendre l'importation, continuez à importer le fichier. en commençant par l'octet suivant. Incluez un
Content-Range
pour indiquer la partie du fichier que vous envoyez. Pour exemple,Content-Range: bytes 43-1999999
indique que vous envoient les octets 44 à 2 000 000 d'octets.
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 ont échoué en raison de la connexion sans interruption. Pour en savoir plus sur la gestion des erreurs5xx
, consultez Erreurs 500, 502, 503, 504. - Pour les erreurs
403 rate limit
, relancez l'importation. Pour en savoir plus sur gestion des erreurs403 rate limit
, reportez-vous à 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 doivent être redémarré en demandant un nouvel URI de session. Importer des sessions expirent également après une semaine d'inactivité.
Importer dans des types Google Docs
Lorsque vous créez un fichier dans Drive, vous pouvez convertir le fichier dans un type de fichier Google Workspace tel que Google Docs ou Google Sheets. Par exemple, vous voulez peut-être transformer un document votre traitement de texte préféré dans un document Docs, caractéristiques.
Pour convertir un fichier dans un type de fichier Google Workspace spécifique, spécifiez le paramètre
Google Workspace mimeType
lors de la création du fichier.
Voici comment convertir un fichier CSV en feuille Google Workspace:
Java
Python
Node.js
PHP
.NET
Pour savoir si une conversion est disponible, consultez le tableau importFormats
de la ressource about
avant de créer le fichier.
Les conversions acceptées sont disponibles dynamiquement dans ce tableau. Quelques exemples
formats d'importation sont les suivants:
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, OpenDocument Presentation | Google Slides |
JPEG, PNG, GIF, BMP, PDF | Google Docs (inclut l'image dans un document) |
Texte brut (type MIME spécial), JSON | Google Apps Script |
Lorsque vous importez et convertissez des contenus multimédias lors d'une requête update
en
un fichier Docs, Sheets ou Slides, le
l'intégralité du contenu du document est remplacée.
Lorsque vous convertissez une image en fichier Docs, Drive utilise
La reconnaissance optique des caractères (OCR) permet de convertir l'image en texte. Vous pouvez
améliorer la qualité de l'algorithme de reconnaissance optique des caractères en spécifiant la valeur BCP applicable
47
dans
ocrLanguage
. Le texte extrait apparaît dans le document à côté de l'image intégrée.
Importez des fichiers à l'aide d'un ID généré à l'avance
L'API Drive vous permet de récupérer une liste d'ID de fichiers pré-générés qui
sont utilisés pour importer et créer des ressources. Les demandes d'importation et de création de fichiers peuvent
utilisez 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
d'ID à créer.
Vous pouvez relancer les importations en toute sécurité à l'aide d'ID pré-générés en cas d'erreur indéterminée
erreur du serveur ou délai d'inactivité. Si le fichier a bien été créé,
Les nouvelles tentatives renvoient une erreur HTTP 409
et ne créent pas de fichiers en double.
Définir du 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 fullText
pour rechercher du contenu depuis votre application. Pour en savoir plus, consultez la section Rechercher
fichiers et dossiers.
Drive indexe automatiquement les documents à rechercher lorsqu'ils
reconnaît le type de fichier, y compris les documents texte, les PDF, les images avec du texte et
d'autres types courants. Si votre application enregistre d'autres types de fichiers (des dessins,
vidéo et raccourcis), vous pouvez améliorer leur visibilité en fournissant
du texte indexable dans le champ contentHints.indexableText
du fichier.
Pour en savoir plus sur le texte indexable, consultez la section Gérer les fichiers métadonnées.