API des paramètres de notification

{{< details >}}

• Édition : Gratuite, GitLab Premium, GitLab Ultimate
• Offre : GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Utilisez cette API pour gérer les paramètres de notification dans GitLab. Pour plus d'informations, voir les e-mails de notification.

Niveaux de notification {#notification-levels}

Les niveaux de notification sont définis dans l'énumération du modèle NotificationSetting.level. Les niveaux suivants sont reconnus :

• disabled : Désactiver toutes les notifications
• participating : Recevoir des notifications pour les fils de discussion auxquels vous avez participé
• watch : Recevoir des notifications pour la plupart des activités
• global : Utiliser vos paramètres de notification globaux
• mention : Recevoir des notifications lorsque vous êtes mentionné(e) dans un commentaire
• custom : Recevoir des notifications pour les événements sélectionnés

Si vous utilisez le niveau custom, vous pouvez contrôler des événements d'e-mail spécifiques. Les événements disponibles sont retournés par NotificationSetting.email_events. Les événements suivants sont reconnus :

Récupérer les paramètres de notification globaux {#retrieve-global-notification-settings}

Récupère le niveau de notification global et l'adresse e-mail.

GET /notification_settings

Exemple de requête :

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/notification_settings"

En cas de succès, renvoie 200 OK et les attributs de réponse suivants :

Exemple de réponse :

{
  "level": "participating",
  "notification_email": "[email protected]"
}

Mettre à jour les paramètres de notification globaux {#update-global-notification-settings}

Met à jour les paramètres de notification et l'adresse e-mail.

PUT /notification_settings

Exemple de requête :

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/notification_settings?level=watch"

Attributs pris en charge :

En cas de succès, renvoie 200 OK et les attributs de réponse suivants :

Exemple de réponse :

{
  "level": "watch",
  "notification_email": "[email protected]"
}

Récupérer les paramètres de notification {#retrieve-notification-settings}

Récupère le niveau de notification pour un groupe ou un projet spécifié.

GET /groups/:id/notification_settings
GET /projects/:id/notification_settings

Exemple de requête :

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/notification_settings"

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/8/notification_settings"

Attributs pris en charge :

En cas de succès, renvoie 200 OK et les attributs de réponse suivants :

Exemple de réponse pour un niveau de notification standard :

{
  "level": "global"
}

Exemple de réponse pour un groupe avec un niveau de notification personnalisé :

{
  "level": "custom",
  "events": {
    "new_release": null,
    "new_note": null,
    "new_issue": null,
    "reopen_issue": null,
    "close_issue": null,
    "reassign_issue": null,
    "issue_due": null,
    "new_merge_request": null,
    "push_to_merge_request": null,
    "reopen_merge_request": null,
    "close_merge_request": null,
    "reassign_merge_request": null,
    "change_reviewer_merge_request": null,
    "merge_merge_request": null,
    "failed_pipeline": null,
    "fixed_pipeline": null,
    "success_pipeline": null,
    "moved_project": true,
    "merge_when_pipeline_succeeds": false,
    "new_epic": null
  }
}

Dans cette réponse :

• true indique que la notification est activée.
• false indique que la notification est désactivée.
• null indique que la notification utilise le paramètre par défaut.

[!note] L'attribut new_epic est disponible uniquement dans les niveaux Premium et Ultimate.

Mettre à jour les paramètres de notification d'un groupe ou d'un projet {#update-group-or-project-notification-settings}

Met à jour les paramètres de notification pour un groupe ou un projet.

PUT /groups/:id/notification_settings
PUT /projects/:id/notification_settings

Exemples de requêtes :

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch"

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true"

Attributs pris en charge :

En cas de succès, renvoie 200 OK et l'un des formats de réponse suivants.

Pour un niveau de notification non personnalisé :

{
  "level": "watch"
}

Pour un niveau de notification personnalisé, la réponse inclut un objet events indiquant l'état de chaque notification :

{
  "level": "custom",
  "events": {
    "new_release": null,
    "new_note": true,
    "new_issue": false,
    "reopen_issue": null,
    "close_issue": null,
    "reassign_issue": null,
    "issue_due": null,
    "new_merge_request": null,
    "push_to_merge_request": null,
    "reopen_merge_request": null,
    "close_merge_request": null,
    "reassign_merge_request": null,
    "change_reviewer_merge_request": null,
    "merge_merge_request": null,
    "failed_pipeline": false,
    "fixed_pipeline": null,
    "success_pipeline": null,
    "moved_project": false,
    "merge_when_pipeline_succeeds": false,
    "new_epic": null
  }
}

Dans cette réponse :

• true indique que la notification est activée.
• false indique que la notification est désactivée.
• null indique que la notification utilise le paramètre par défaut.

[!note] L'attribut new_epic est disponible uniquement dans les niveaux Premium et Ultimate.