Cette page a été traduite par l'API Cloud Translation.

Importations réactivables

Vous pouvez importer des vidéos de manière plus fiable en utilisant le protocole d'importation avec reprise pour les API Google. Ce protocole vous permet de reprendre une opération d'importation après une interruption du réseau ou un autre échec de transmission, ce qui vous fait gagner du temps et de la bande passante en cas de défaillances réseau.

L'utilisation des importations réactivables est particulièrement utile dans les cas suivants:

Vous transférez des fichiers volumineux.
La probabilité d'une interruption du réseau est élevée.
Les importations proviennent d'un appareil dont la bande passante est faible ou dont la connexion Internet est instable, comme un appareil mobile.

Ce guide explique la séquence de requêtes HTTP qu'une application envoie pour importer des vidéos à l'aide d'un processus d'importation avec reprise. Ce guide est principalement destiné aux développeurs qui ne peuvent pas utiliser les bibliothèques clientes des API Google, certaines d'entre elles proposant une prise en charge native des importations réactivables. En fait, le guide YouTube Data API : importer une vidéo explique comment utiliser la bibliothèque cliente des API Google pour Python pour importer une vidéo à l'aide d'un processus d'importation récapitulatif.

Remarque:Vous pouvez également afficher la série de requêtes effectuées pour l'importation récapitulative ou toute autre opération d'API à l'aide de l'une des bibliothèques clientes des API Google avec la journalisation HTTPS activée. Par exemple, pour activer la trace HTTP pour Python, utilisez la bibliothèque httplib2:

httplib2.debuglevel = 4

Étape 1 : Démarrez une session avec reprise

Pour démarrer une importation de vidéo avec reprise, envoyez une requête POST à l'URL suivante. Dans l'URL, définissez la valeur du paramètre part sur la valeur appropriée pour votre requête. N'oubliez pas que la valeur du paramètre identifie les parties contenant les propriétés que vous définissez, ainsi que les parties que vous souhaitez inclure dans la réponse de l'API. Les valeurs des paramètres dans l'URL de la requête doivent être encodées au format URL.

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

Définissez le corps de la requête sur une ressource video. Définissez également les en-têtes de requête HTTP suivants:

Authorization : jeton d'autorisation de la requête.
Content-Length : nombre d'octets fournis dans le corps de la requête. Notez que vous n'avez pas besoin de fournir cet en-tête si vous utilisez l'encodage de transfert fragmenté.
Content-Type : définissez la valeur sur application/json; charset=UTF-8.
X-Upload-Content-Length : nombre d'octets qui seront importés dans les requêtes ultérieures. Définissez cette valeur sur la taille du fichier que vous importez.
x-upload-content-type : type MIME du fichier que vous importez. Vous pouvez importer des fichiers avec n'importe quel type MIME vidéo (video/*) ou un type MIME de application/octet-stream.

L'exemple suivant montre comment lancer une session avec reprise pour importer une vidéo. La requête définit (et récupère) des propriétés dans les parties snippet et status de la ressource video, et récupère également des propriétés dans la partie contentdetails de la ressource.

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

L'exemple suivant montre une requête POST dans laquelle toutes ces valeurs sont renseignées, à l'exception du jeton d'authentification. La valeur categoryId de l'exemple correspond à une catégorie de vidéos. La liste des catégories acceptées peut être récupérée à l'aide de la méthode videoCategories.list de l'API.

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

Étape 2 : Enregistrez l'URI de la session avec reprise

Si votre requête aboutit, le serveur API répond par un code d'état HTTP 200 (OK) et la réponse inclut un en-tête HTTP Location qui spécifie l'URI de la session pouvant être reprise. Il s'agit de l'URI que vous utiliserez pour importer votre fichier vidéo.

L'exemple ci-dessous montre un exemple de réponse de l'API à la requête de l'étape 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

Étape 3 : Importez le fichier vidéo

Après avoir extrait l'URI de session de la réponse de l'API, vous devez importer le contenu du fichier vidéo à cet emplacement. Le corps de la requête correspond au contenu du fichier binaire de la vidéo que vous mettez en ligne. L'exemple ci-dessous montre le format de la requête.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

La requête définit les en-têtes de requête HTTP suivants:

Authorization : jeton d'autorisation de la requête.
Content-Length : taille du fichier que vous importez. Cette valeur doit être identique à celle de l'en-tête de requête HTTP X-Upload-Content-Length à l'étape 1.
Content-Type : type MIME du fichier que vous importez. Cette valeur doit être identique à celle de l'en-tête de requête HTTP X-Upload-Content-Type à l'étape 1.

Étape 4 : Finalisez le processus de mise en ligne

Votre demande entraînera l'un des scénarios suivants:

Votre importation a bien été effectuée.

Le serveur de l'API répond avec un code de réponse HTTP 201 (Created). Le corps de la réponse correspond à la ressource video que vous avez créée.
Votre importation a échoué, mais vous pouvez la reprendre.

Vous devriez pouvoir reprendre une importation dans les cas suivants:
- Votre requête est interrompue, car la connexion entre votre application et le serveur de l'API est perdue. Dans ce cas, vous ne recevrez pas de réponse de l'API.
- La réponse de l'API spécifie l'un des codes de réponse 5xx suivants. Votre code doit utiliser une stratégie d'intervalle exponentiel entre les tentatives lors de la reprise des importations après avoir reçu l'un de ces codes de réponse.
  - 500 – Internal Server Error
  - 502 – Bad Gateway
  - 503 – Service Unavailable
  - 504 – Gateway Timeout
Pour reprendre une importation, suivez les instructions pour vérifier l'état de l'importation et reprendre une importation ci-dessous. N'oubliez pas que chaque URI de session avec reprise possède une durée de vie limitée et finit par expirer. C'est pourquoi nous vous recommandons de démarrer une importation avec reprise dès que vous obtenez l'URI de session et de reprendre une importation interrompue peu après son interruption.
Votre importation a échoué de manière permanente.

En cas d'échec de l'importation, la réponse contient une réponse d'erreur qui permet d'expliquer la cause de l'échec. Pour une importation qui échoue définitivement, la réponse de l'API contient un code de réponse 4xx ou 5xx autre que ceux listés ci-dessus.

Si vous envoyez une requête avec un URI de session expiré, le serveur renvoie un code de réponse HTTP 404 (Not Found). Dans ce cas, vous devez lancer une nouvelle importation avec reprise, obtenir un nouvel URI de session et reprendre l'importation depuis le début à l'aide du nouvel URI.

Étape 4.1: Vérifier l'état d'une importation

Pour vérifier l'état d'une importation avec reprise interrompue, envoyez une requête PUT vide à l'URL d'importation que vous avez récupérée à l'étape 2 et utilisée à l'étape 3. Dans votre requête, définissez la valeur de l'en-tête Content-Range sur bytes */CONTENT_LENGTH, où CONTENT_LENGTH correspond à la taille du fichier que vous importez.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

Étape 4.2: Traiter la réponse de l'API

Si l'importation est déjà terminée, qu'elle ait réussi ou échoué, l'API renvoie la même réponse qu'elle a envoyée lorsque l'importation s'est terminée à l'origine.

Toutefois, si l'importation a été interrompue ou est toujours en cours, la réponse de l'API comporte un code de réponse HTTP 308 (Resume Incomplete). Dans la réponse, l'en-tête Range spécifie le nombre d'octets du fichier déjà importés avec succès.

La valeur de l'en-tête est indexée à partir de 0. Par conséquent, une valeur d'en-tête de 0-999999 indique que les 1,000,000 premiers octets du fichier ont été importés.
Si aucun fichier n'a encore été importé, la réponse de l'API n'inclut pas l'en-tête Range.

L'exemple de réponse ci-dessous montre le format d'une réponse d'API pour une importation avec reprise:

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

Si la réponse de l'API inclut également l'en-tête Retry-After, utilisez la valeur de cet en-tête pour déterminer quand tenter de reprendre l'importation.

Étape 4.3: Reprendre l'importation

Pour reprendre l'importation, envoyez une autre requête PUT à l'URL d'importation capturée à l'étape 2. Définissez le corps de la requête sur le code binaire de la partie du fichier vidéo qui n'a pas encore été mise en ligne.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

Vous devez définir les en-têtes de requête HTTP suivants:

Authorization : jeton d'autorisation de la requête.
Content-Length : taille, en octets, du contenu qui n'a pas encore été importé. Si vous importez le reste d'un fichier, vous pouvez calculer cette valeur en soustrayant la valeur FIRST_BYTE de la valeur TOTAL_CONTENT_LENGTH. Les deux valeurs sont utilisées dans l'en-tête Content-Range.
Content-Range : partie du fichier que vous importez. La valeur de l'en-tête comprend trois valeurs:
- FIRST_BYTE : indice numérique (sur base 0) du numéro d'octet à partir duquel vous reprenez l'importation. Cette valeur est supérieure de 1 au deuxième nombre de l'en-tête Range récupéré à l'étape précédente. Dans l'exemple précédent, la valeur de l'en-tête Range était 0-999999. Par conséquent, le premier octet d'une importation ultérieure avec reprise serait 1000000.
- LAST_BYTE : index numérique (sur base 0) du dernier octet du fichier binaire que vous importez. Il s'agit généralement du dernier octet du fichier. Par exemple, si la taille du fichier est de 3000000 octets, le dernier octet du fichier est le numéro 2999999.
- TOTAL_CONTENT_LENGTH : taille totale du fichier vidéo en octets. Cette valeur est identique à l'en-tête Content-Length spécifié dans la requête d'importation d'origine.
Remarque:Vous ne pouvez pas importer un bloc non continu du fichier binaire. Si vous essayez d'importer un bloc non continu, aucun des contenus binaires restants ne sera importé.

Par conséquent, le premier octet importé lors d'une importation reprise doit être l'octet suivant le dernier octet déjà importé sur YouTube. (voir la discussion sur l'en-tête Range à l'étape 4.2) ;

Par conséquent, si le dernier octet de l'en-tête Range est 999999, le premier octet de la requête pour reprendre l'importation doit être l'octet 1000000. (Les deux nombres utilisent un index en base 0.) Si vous essayez de reprendre l'importation à partir de l'octet 999999 ou inférieur (octets en chevauchement) ou de l'octet 1000001 ou supérieur (octets ignorés), aucun contenu binaire ne sera importé.

Importer un fichier par fragments

Au lieu d'essayer d'importer un fichier entier et de reprendre l'importation en cas d'interruption du réseau, votre application peut diviser le fichier en plusieurs fragments et envoyer une série de requêtes pour importer les fragments dans l'ordre. Cette approche est rarement nécessaire et est en fait déconseillée, car elle nécessite des requêtes supplémentaires, ce qui a des conséquences sur les performances. Toutefois, cela peut être utile si vous essayez d'afficher un indicateur de progression sur un réseau très instable.

Les instructions pour importer un fichier par blocs sont pratiquement identiques au processus en quatre étapes expliqué précédemment dans ce guide. Toutefois, les requêtes permettant de commencer à importer un fichier (étape 3 ci-dessus) et de reprendre une importation (étape 4.3 ci-dessus) définissent les valeurs des en-têtes Content-Length et Content-Range différemment lorsqu'un fichier est importé par blocs.

La valeur de l'en-tête Content-Length spécifie la taille du segment envoyé par la requête. Notez les restrictions suivantes concernant les tailles de bloc:
- La taille des fragments doit être un multiple de 256 Ko. (Cette restriction ne s'applique pas au dernier fragment, car la taille de l'ensemble du fichier peut ne pas être un multiple de 256 Ko.) N'oubliez pas que les blocs plus importants sont plus efficaces.
- La taille des fragments doit être la même pour chaque requête de la séquence d'importation, à l'exception de la dernière requête, qui spécifie la taille du dernier fragment.
L'en-tête Content-Range spécifie les octets du fichier que la requête importe. Les instructions de définition de l'en-tête Content-Range à l'étape 4.3 s'appliquent lorsque vous définissez cette valeur.

Par exemple, une valeur de bytes 0-524287/2000000 indique que la requête envoie les 524 288 premiers octets (256 x 2 048) dans un fichier de 2 000 000 octets.

L'exemple ci-dessous montre le format de la première d'une série de requêtes qui importera un fichier de 2 000 000 octets par blocs:

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

Si une requête autre que la requête finale aboutit, le serveur d'API répond par une réponse 308 (Resume Incomplete). Le format de la réponse sera le même que celui décrit dans l'étape 4.2: Traiter la réponse de l'API ci-dessus.

Utilisez la valeur supérieure affichée dans l'en-tête Range de la réponse de l'API pour déterminer où démarrer le prochain fragment. Continuez à envoyer des requêtes PUT, comme décrit à l'étape 4.3 Répondre à l'importation, pour importer les fragments de fichier suivants jusqu'à ce que le fichier entier soit importé.

Une fois le fichier importé, le serveur renvoie un code de réponse HTTP 201 (Created) et renvoie les parties demandées de la ressource vidéo nouvellement créée.

Si une requête est interrompue ou si votre application reçoit un code de réponse 5xx, suivez la procédure décrite à l'étape 4 pour terminer l'importation. Toutefois, plutôt que d'essayer d'importer le reste du fichier, continuez simplement à importer des fragments à partir du point où vous reprenez l'importation. Veillez à vérifier l'état de l'importation pour déterminer où reprendre l'importation du fichier. Ne partez pas du principe que le serveur a reçu tous les octets envoyés dans la requête précédente (ou qu'il n'en a reçu aucun).

Remarque:Vous pouvez également demander l'état d'une importation active entre les fragments importés. (L'importation n'a pas besoin d'avoir été interrompue pour que vous puissiez récupérer son état.)