Développement du SDK Box
Avant de coder
- Inspectez la version et les types du SDK installé, le runtime, l'authentification, l'acteur Box, le wrapper client existant et la charge de travail attendue. Conservez la version majeure du SDK du projet sauf si une migration est requise ou demandée.
- Décidez où vivent le client, la gestion des tokens, le limiteur de débit, la politique de retry et la journalisation. Tracez les chemins de requête existants pour les appels en doublon ou les contrôles contournés. Pour les opérations répétées, estimez les appels, le débit des requêtes, la taille des transferts et les besoins de redémarrage avant de choisir une approche.
- Vérifiez les arguments, le type de retour, la pagination et les erreurs de chaque méthode Box par rapport au SDK installé et à la documentation Box actuelle. Les versions majeures des SDK Python et Node ont des interfaces incompatibles ; ne copiez pas les appels entre les versions.
- Implémentez et exécutez des tests ciblés plus la vérification de type ou la compilation du projet. Vérifiez les permissions et le comportement de transfert avec un compte de test autorisé le cas échéant ; la compilation seule ne peut pas les prouver.
Consultez la référence SDK pertinente : Python ou TypeScript/Node. Pour les travaux à l'échelle des collections, consultez opérations en masse. Pour les uploads ou téléchargements, consultez transfert de fichiers.
Contraintes de conception
- Choisissez l'API pour le résultat demandé : bytes originaux, preview, métadonnées ou listing. Utilisez l'endpoint file-content pour les bytes originaux et les representations pour les previews ; un listing est de la découverte, pas un téléchargement. Demandez les champs nécessaires et paginisez jusqu'à la fin réelle de l'endpoint, en utilisant des marqueurs si supportés pour les collections volumineuses ou changeantes.
- Préférez les opérations de copie, déplacement ou métadonnées côté Box quand le contenu reste dans Box. Utilisez les événements ou webhooks avec rattrapage au lieu de scans complets répétés pour suivre les modifications.
- Réutilisez le client SDK et le cache de tokens. Incluez l'authentification, la découverte, les retries et la vérification dans les budgets d'appels API ; les appels d'application personnalisée comptent vers l'allocation d'entreprise même sans 429s.
- Bornez les requêtes concurrentes par acteur et endpoint. Les SDK Box actuels réessaient les 429s avec
Retry-After; vérifiez la version installée et gardez un propriétaire de retry. Pour les anciens SDK ou HTTP personnalisé, utilisez un backoff borné qui honoreRetry-After. Réconciliez les écritures incertaines avant de réessayer ; diagnostiquez les 401/403 plutôt que de les répéter inchangés. - Conservez les secrets client et les clés de compte de service côté serveur. Utilisez l'acteur prévu et le moindre privilège ; ne journalisez jamais les credentials.
Observabilité
Instrumentez le client SDK ou le wrapper une fois. Enregistrez les succès et les échecs avec l'opération, l'ID d'élément, l'ID acteur ou tenant sûr, le statut, l'ID de requête Box si disponible, la durée, les bytes si pertinent et l'ID de travail. Capturez les 429s et le délai de retry uniquement si les hooks SDK ou l'instrumentation de transport les exposent ; les retries cachés sont inconnus, pas zéro. Pour les travaux en masse, conservez les résultats durables par élément et surveillez le débit et les appels par rapport au plan. Surfacez l'étranglement ou l'utilisation inattendue pendant l'exécution. Configurez le volume et la rétention des logs ; omettez le contenu, les credentials et les URLs signées.
Rapport d'achèvement
Après chaque tâche SDK, énoncez brièvement ce qui a changé et ce qui a été vérifié ; les choix de conception matériels et leurs raisons ; et les alternatives viables avec leurs compromis. Pour les travaux en masse, incluez les hypothèses du budget d'appels. Énoncez tout comportement non vérifié.