Décodage Protobuf

ApiCatcher prend en charge le décodage des données binaires Protobuf des requêtes/réponses HTTP/HTTPS en texte brut pour une visualisation et une analyse faciles.

Par défaut, ApiCatcher détecte automatiquement si l'en-tête Content-Type de la requête/réponse correspond aux types de contenu Protobuf courants tels que application/protobuf ou application/x-protobuf. Si c'est le cas, il tente de décoder.

private static func isProtobufContentType(_ contentType: String) -> Bool {
    let ct = contentType.lowercased().trimmingCharacters(in: .whitespacesAndNewlines)
    let mimeType = ct.components(separatedBy: ";").first?.trimmingCharacters(in: .whitespaces) ?? ct
    return mimeType == "application/protobuf"
        || mimeType == "application/x-protobuf"
        || mimeType == "application/x-google-protobuf"
        || mimeType == "application/grpc"
        || mimeType == "application/grpc+proto"
        || mimeType == "application/protobuf+json"
        || mimeType == "x-protobuf"
}

Si le Content-Type ne fait pas partie des types ci-dessus, ApiCatcher ne tentera pas de décoder automatiquement, mais vous pouvez utiliser l'outil de décodage pour décoder manuellement — cliquez sur l'icône "Unlock" de la carte Body, passez à "Protobuf", puis cliquez sur le bouton "Décoder".

Le résultat de décodage par défaut est peu lisible car il n'y a pas de noms de champs. Si vous disposez d'un fichier *.desc, vous pouvez l'importer pour décoder les noms de champs. Si le fichier *.desc est correct, le résultat sera converti au format JSON, beaucoup plus lisible. Voici une comparaison des résultats avec et sans fichier *.desc :

Comparaison des résultats de décodage Protobuf avec et sans fichier descripteur : à gauche sans noms de champs, à droite avec noms de champs complets

Importer des fichiers descripteurs Protobuf (*.desc)

Qu'est-ce qu'un fichier *.desc ?

Un fichier *.desc est le résultat sérialisé binaire d'un Descripteur de Fichier Protobuf (File Descriptor), contenant toutes les structures de messages, énumérations, définitions de services et autres métadonnées définies dans les fichiers Proto. Il est essentiel pour analyser les données binaires Protobuf.

Si vous n'avez que des fichiers *.proto, vous devez les convertir en fichier *.desc avant de pouvoir l'utiliser pour le décodage Protobuf.

Comment générer un fichier *.desc ?

Si vous avez un ensemble de fichiers *.proto, vous pouvez utiliser l'outil en ligne de commande protoc pour générer un ou plusieurs fichiers *.desc. Étapes :

1. Installer l'outil en ligne de commande protobuf :

brew install protobuf

2. Préparer les fichiers proto :

Créez un dossier input et copiez-y tous les fichiers *.proto.

3. Exécuter la commande de génération :

protoc --descriptor_set_out=output.desc \
  --include_imports \
  -I=/path/to/input \
  /path/to/input/*.proto

Description des paramètres :

Paramètre	Description
`--descriptor_set_out=output.desc`	Spécifie le chemin du fichier descripteur de sortie
`--include_imports`	Inclut tous les fichiers import dépendants, garantissant un résultat autonome sans dépendances supplémentaires
`-I=/path/to/input`	Spécifie le chemin de recherche des fichiers proto (préfixe pour les chemins d'import)
`/path/to/input/*.proto`	Les fichiers proto à compiler (prend en charge les caractères génériques)

Après exécution, un fichier output.desc sera généré dans le répertoire courant. Transférez-le sur votre téléphone et importez-le dans ApiCatcher pour une utilisation ultérieure.

Importer des fichiers *.desc et gérer les fichiers *.desc importés

Lorsque le Body de la requête peut être décodé en Protobuf, la carte affichera l'indication : "Sélectionnez un fichier *.desc pour décoder les noms de champs" et proposera un bouton de sélection. Cliquez sur le bouton de sélection pour choisir un fichier *.desc importé, et les noms de champs seront décodés. Vous pouvez également importer un fichier à ce moment-là. Les fichiers importés sont mis en cache localement et peuvent être gérés dans "Paramètres → Gestionnaire de fichiers Protobuf".

Cliquez sur le bouton de sélection pour choisir un fichier *.desc importé afin de décoder les noms de champs