Skip to content

features

Tirer sur les membres

Tirer des membres vérifiés vers un nouveau serveur avec une attribution automatique des rôles. Comprendre comment les jetons OAuth2 permettent le pulling, les limites de taux, les cooldowns, les filtres, le mappage des rôles et le pull worker.

Vue d'ensemble

L'extraction de membres est le processus d'ajout de membres qui ont vérifié par l'intermédiaire d'un de vos serveurs à un autre serveur. Lorsque les membres vérifient via Restore Hub, ils accordent la portée OAuth2 guilds.join, qui autorise Restore Hub à les ajouter à n'importe quel serveur où vous avez un bot. Pulling utilise ces jetons stockés pour ajouter des membres à votre serveur cible et leur attribuer un rôle.

Il s'agit d'un modèle de consentement unique : le membre autorise lors de la vérification et peut révoquer l'accès à tout moment via les paramètres des applications autorisées de Discord. Restore Hub ne demande pas à nouveau le consentement.

Comment les jetons OAuth2 permettent le pulling

Lorsqu'un membre termine la vérification, Restore Hub stocke son jeton d'accès OAuth2 et son jeton de rafraîchissement (tous deux cryptés avec AES-256). Le jeton d'accès est valable pendant 7 jours. Le jeton de rafraîchissement est valide pendant 30 jours.

Lorsqu'une tâche d'extraction est exécutée, Restore Hub utilise la portée guilds.join avec le jeton d'accès du membre pour l'ajouter au serveur cible via le point de terminaison PUT /guilds/{guild_id}/members/{user_id} de Discord. Ce point d'accès accepte également un tableau de rôles, permettant l'attribution immédiate d'un rôle lors de l'adhésion.

Si le jeton d'accès a expiré, Restore Hub l'actualise automatiquement à l'aide du jeton d'actualisation avant de tenter l'extraction. Si le jeton de rafraîchissement a également expiré (le membre ne s'est pas réactivé depuis 30 jours) ou si le membre a révoqué son accès, le membre est marqué comme "non extractible".

Mécanisme de rafraîchissement des jetons

Restore Hub rafraîchit proactivement les tokens 5 minutes avant leur expiration (TOKEN_REFRESH_BUFFER_MS = 5 minutes). Au cours d'une tâche d'extraction, si un jeton est à moins de 5 minutes de son expiration, Restore Hub le rafraîchit avant de l'utiliser.

Lorsqu'un rafraîchissement réussit, le nouveau jeton d'accès, le jeton de rafraîchissement et l'horodatage d'expiration sont sauvegardés (cryptés) dans la base de données. Lorsqu'un rafraîchissement échoue (l'utilisateur a révoqué l'accès, le jeton a expiré au-delà du renouvellement, une erreur de l'API Discord), le drapeau isPullable du membre est mis à faux.

Conseil : les membres peuvent retrouver leur statut de membre "retirable" en procédant à une nouvelle vérification. Les nouveaux jetons OAuth2 remplacent les anciens.

Qu'est-ce que le terme "extractible" signifie ?

Un membre est marqué comme "extractible" (isPullable = true) lorsqu'il possède des jetons OAuth2 valides et non périmés. Un membre devient "non extractible" lorsque :

  • Leur jeton d'accès a expiré ET le jeton de rafraîchissement a également expiré (pas de revérification en ~30 jours)
  • Ils ont révoqué l'accès à Restore Hub dans Discord Settings → Authorized Apps (paramètres de Discord → applications autorisées)
  • Une tentative de rafraîchissement du jeton a échoué en raison d'une erreur de l'API Discord
  • Ils ont été marqués manuellement comme non extractibles par le propriétaire du serveur

Démarrage d'une traction

Vous pouvez lancer un tirage à partir de trois endroits : le tableau de bord, une commande Discord ou l'API REST.

  1. Depuis le tableau de bord - Naviguez vers votre serveur source → Membres → Extraire les membres. Sélectionnez le serveur cible, définissez éventuellement un rôle, une limite et des filtres, puis cliquez sur "Start Pull".
  2. Depuis Discord (Premium+) - Utilisez la commande /pull dans votre serveur source. Spécifiez l'ID du serveur cible et le rôle optionnel.
  3. Via l'API - POST /api/v1/servers/:id/pull avec un corps JSON spécifiant targetGuildId, roleId, limit, preserveRoles, roleMapping, et filter.
POST /api/v1/servers/:id/pull
{
  "targetGuildId" : "123456789012345678",
  "roleId" : "987654321098765432",
  "limit" : 500,
  "preserveRoles" : false,
  "roleMapping" : {
    "111111111111111111": "222222222222222222"
  },
  "filter" : {
    "roleIds" : ["333333333333333333"],
    "memberIds" : ["444444444444444444"]
  }
}

Limitation du taux

L'API de Discord a des limites strictes sur le point de terminaison PUT /guilds/{guild_id}/members/{user_id}. Restore Hub traite les membres à environ 50 par minute (PULL_RATE_LIMIT = 50) pour rester dans les limites de Discord.

Cela signifie qu'un tirage de 1 000 membres prend environ 20 minutes. Un appel de 5 000 membres prend environ 100 minutes. L'agent d'appel gère le temps automatiquement - vous n'avez pas à vous soucier d'atteindre les limites de débit de Discord.

Avertissement : Le dépassement des limites de débit de Discord peut entraîner le bannissement temporaire ou permanent de votre bot. La limitation de débit intégrée à Restore Hub permet d'éviter cela, mais sachez que les gros tirages prennent du temps.

Temps de recharge par plan

Pour éviter les abus, chaque plan est assorti d'une période de refroidissement entre les tirages pour le même serveur source :

| Plan de récupération entre les tractions
|---|---|
| Gratuit - 6 heures - Premium - 1 heure
| Premium - 1 heure
| Entreprise - 15 minutes - Pas de délai
| Entreprise - Pas de délai d'attente - Pas de délai d'attente

Astuce : Le délai d'attente s'applique à chaque serveur source, et non à l'ensemble des serveurs. Si vous disposez de deux serveurs sources, vous pouvez tirer simultanément sur les deux, même avec le plan gratuit.

Cartographie des rôles

Lorsque vous extrayez des membres, vous pouvez éventuellement faire correspondre les rôles du serveur source aux rôles du serveur cible. Cette option est utile lorsque vous souhaitez conserver les rôles des membres sur plusieurs serveurs.

Le champ roleMapping est un objet JSON dont les clés sont des ID de rôle du serveur source et les valeurs des ID de rôle du serveur cible. Lorsqu'un membre est extrait, Restore Hub recherche ses rôles dans le serveur source et lui attribue les rôles mappés correspondants dans le serveur cible.

Si preserveRoles est défini sur true sans roleMapping, Restore Hub tente de faire correspondre les rôles par nom. Les rôles dont les noms sont identiques dans les deux serveurs sont automatiquement mappés.

Filtres à tirettes

Vous pouvez restreindre les membres inclus dans un tirage à l'aide de filtres :

| Filtre - Description - Filtre - Description - Filtre - Description - Filtre - Filtre - Description
|---|---|
| roleIds | N'extraire que les membres qui ont au moins l'un des rôles spécifiés dans le serveur source |
| memberIds | N'extraire que des membres spécifiques par leur ID d'utilisateur Discord
| limite | Nombre maximum de membres à extraire (par exemple, 500). S'il n'est pas défini, tous les membres pouvant être extraits sont inclus

Extraction des statuts des travaux

Chaque tâche d'extraction passe par une série de statuts. Vous pouvez suivre la progression dans le tableau de bord ou via GET /api/v1/pulls/:id.

| Statut | Signification |
|---|---|
| PENDING - Travail créé, en attente d'être mis en file d'attente
| QUEUED - Travail ajouté à la file d'attente du travailleur, en attente de prise en charge par un travailleur
| RUNNING | Le travailleur est en train de traiter les membres (PullCount s'incrémente en temps réel) |
| COMPLETED | Tous les membres ont été traités (certains peuvent avoir échoué ou avoir été ignorés)
| FAILED | La tâche entière a échoué en raison d'une erreur critique (par exemple, le bot a été supprimé du serveur cible)
| CANCELLED | Le travail a été annulé par l'utilisateur avant d'être achevé

Compteurs de tâches à tirer

Pendant et après un tirage, les compteurs suivants permettent de suivre l'évolution de la situation :

  • totalMembers - Le nombre total de membres qui seront traités (en fonction des filtres et de la limite).
  • compteTiré - Nombre de membres ajoutés avec succès au serveur cible.
  • compte d'échec - Nombre de membres qui n'ont pas pu être extraits (jeton expiré, accès révoqué par l'utilisateur, erreur de l'API Discord).
  • skippedCount - Nombre de membres ignorés (déjà dans le serveur cible, bannis du serveur cible, etc.)
  • progrès - Calculé comme suit : (pulledCount + failedCount + skippedCount) / totalMembers * 100.

Le travailleur à la tire

Les travaux "pull" sont traités par un travailleur en arrière-plan (file d'attente de travaux BullMQ). Le travailleur :

  • Déqueue le prochain travail d'extraction en attente.
  • Charge tous les membres extractibles du serveur source (en appliquant des filtres).
  • Pour chaque membre : vérifie si son jeton est valide, le rafraîchit si nécessaire, appelle l'API de Discord pour l'ajouter au serveur cible avec le(s) rôle(s) spécifié(s), et met à jour les compteurs.
  • Respecte la limite de 50 minutes en espaçant les appels à l'API.
  • Gère les erreurs avec élégance - si un seul membre échoue, le travail se poursuit avec le membre suivant.
  • Met à jour le statut du travail en indiquant COMPLETE ou FAILED lorsqu'il est terminé.
  • Enregistre toutes les erreurs dans le champ JSON errorLog pour le débogage.

Que se passe-t-il lorsque les jetons expirent ?

Si le jeton d'accès d'un membre a expiré mais que son jeton de rafraîchissement est toujours valide, l'agent rafraîchit automatiquement le jeton et réessaie. Si le jeton de rafraîchissement a également expiré ou a été révoqué, le membre est marqué comme ne pouvant pas être tiré (isPullable = false) et est compté dans failedCount.

Pour minimiser les problèmes d'expiration des jetons, encouragez les membres à revérifier périodiquement ou mettez en place des alertes pour surveiller votre pourcentage de membres pouvant être retirés.

Pull multi-serveur (Entreprise)

Avec le plan Entreprise, vous pouvez transférer des membres de plusieurs serveurs sources vers un seul serveur cible en une seule opération. Cette fonction est utile pour consolider les communautés. L'extraction sur plusieurs serveurs respecte les limites de débit individuelles et traite les membres de chaque serveur source de manière séquentielle.

Retrait automatique des alertes (Business+)

Sur Business et au-delà, vous pouvez configurer des alertes (nuke, raid, suppression) pour déclencher automatiquement une extraction vers un serveur de sauvegarde. Si votre serveur est compromis, Restore Hub peut automatiquement commencer à extraire vos membres vérifiés vers un serveur sûr sans intervention manuelle.

Tirer sur les membres — Restore Hub Docs | Restore Hub