{"meta":{"title":"Écriture de scripts avec l’API REST et Ruby","intro":"Découvrez comment écrire un script en utilisant le SDK Octokit.rb pour interagir avec l’API REST.","product":"API REST","breadcrumbs":[{"href":"/fr/enterprise-cloud@latest/rest","title":"API REST"},{"href":"/fr/enterprise-cloud@latest/rest/guides","title":"Guides"},{"href":"/fr/enterprise-cloud@latest/rest/guides/scripting-with-the-rest-api-and-ruby","title":"Script avec Ruby"}],"documentType":"article"},"body":"# Écriture de scripts avec l’API REST et Ruby\n\nDécouvrez comment écrire un script en utilisant le SDK Octokit.rb pour interagir avec l’API REST.\n\n## À propos d’Octokit.rb\n\nSi vous souhaitez écrire un script avec Ruby pour interagir avec l’API REST de GitHub, GitHub vous recommande d’utiliser le SDK Octokit.rb. Octokit.rb est maintenu par GitHub. Le SDK implémente les meilleures pratiques et vous permet d’interagir plus facilement avec l’API REST via Ruby. Octokit.rb fonctionne avec tous les navigateurs modernes, Node.rb et Deno. Pour plus d’informations sur Octokit.rb, consultez [le fichier README d'Octokit.rb](https://github.com/octokit/octokit.rb/#readme).\n\n## Prérequis\n\nCe guide suppose que vous êtes familiarisé avec Ruby et l’API REST GitHub REST API. Pour plus d’informations sur l’API REST, consultez [Prise en main de l’API REST](/fr/enterprise-cloud@latest/rest/guides/getting-started-with-the-rest-api).\n\nVous devez installer et importer le gemme `octokit` pour utiliser la bibliothèque Octokit.rb. Ce guide utilise les instructions d'importation conformément aux conventions de Ruby. Pour en savoir plus sur les différentes méthodes d’installation, consultez [la section Installation du fichier README d’Octokit.rb](https://github.com/octokit/octokit.rb/#installation).\n\n## Instanciation et authentification\n\n> \\[!WARNING]\n> Gérez vos informations d’authentification comme un mot de passe.\n>\n> Pour que vos informations d’identification restent sécurisées, vous pouvez les stocker sous forme de secret et exécuter votre script par le biais de GitHub Actions. Pour plus d’informations, consultez « [Utilisation de secrets dans GitHub Actions](/fr/enterprise-cloud@latest/actions/security-guides/encrypted-secrets) ».\n\n> Vous pouvez également stocker vos informations d'identification en tant que secret Codespaces et exécuter votre script dans Codespaces. Pour plus d’informations, consultez « [Gestion des secrets spécifiques à votre compte pour GitHub Codespaces](/fr/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces) ».\n\n> Si ces options ne sont pas possibles, envisagez d’utiliser un autre service CLI pour stocker vos informations d’identification de façon sécurisée.\n\n### Authentification avec un personal access token\n\nSi vous voulez utiliser l’API REST GitHub à des fins personnelles, vous pouvez créer un personal access token. Pour plus d’informations sur la création d’un personal access token, consultez [Gestion de vos jetons d’accès personnels](/fr/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).\n\nTout d’abord, exigez la bibliothèque `octokit`. Ensuite, créez une instance de `Octokit` en faisant passer votre personal access token comme l’option `access_token`. Dans l’exemple suivant, remplacez `YOUR-TOKEN` par vos personal access token.\n\n```ruby copy\nrequire 'octokit'\n\noctokit = Octokit::Client.new(access_token: 'YOUR-TOKEN')\n```\n\n### Authentification avec un(e) GitHub App\n\nSi vous voulez utiliser l’API au nom d’une organisation ou d’un autre utilisateur, GitHub vous recommande d’utiliser une GitHub App. Si un point de terminaison est disponible pour GitHub Apps, la documentation de référence de REST pour ce point de terminaison indique quel type de jeton GitHub App est nécessaire. Pour plus d’informations, consultez « [Inscription d’une application GitHub](/fr/enterprise-cloud@latest/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) » et « [À propos de l’authentification avec une application GitHub](/fr/enterprise-cloud@latest/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) ».\n\nAu lieu d’exiger `octokit`, créez une instance de `Octokit::Client` en transmettant vos informations GitHub App en tant qu’options. Dans l’exemple suivant, remplacez `APP_ID` par l’ID d’application, `PRIVATE_KEY` avec la clé privée de votre application et `INSTALLATION_ID` avec l’ID de l’installation de votre application pour laquelle vous souhaitez vous authentifier. Vous pouvez trouver l’ID de votre application et générer une clé privée dans la page des paramètres de votre application. Pour plus d’informations, consultez « [Gestion des clés privées pour les applications GitHub](/fr/enterprise-cloud@latest/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) ». Vous pouvez obtenir un ID d’installation avec les points de terminaison `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation` ou `GET /orgs/{org}/installation`. Pour plus d’informations, consultez [Points de terminaison d’API REST pour GitHub Apps](/fr/enterprise-cloud@latest/rest/apps/apps).\n\n```ruby copy\nrequire 'octokit'\n\napp = Octokit::Client.new(\n  client_id: APP_ID,\n  client_secret: PRIVATE_KEY,\n  installation_id: INSTALLATION_ID\n)\n\noctokit = Octokit::Client.new(bearer_token: app.create_app_installation.access_token)\n```\n\n### Authentification dans GitHub Actions\n\nSi vous voulez utiliser l’API dans un workflow GitHub Actions, GitHub vous recommande d’être authentifié avec le jeton `GITHUB_TOKEN` intégré au lieu de créer un jeton. Vous pouvez accorder des autorisations au `GITHUB_TOKEN` avec la clé `permissions`. Pour plus d’informations sur `GITHUB_TOKEN`, consultez [GITHUB\\_TOKEN](/fr/enterprise-cloud@latest/actions/concepts/security/github_token).\n\nSi votre workflow doit accéder à des ressources en dehors du dépôt du workflow, vous ne pourrez pas utiliser `GITHUB_TOKEN`. Dans ce cas, stockez vos informations d’identification sous forme de secret et remplacez `GITHUB_TOKEN` dans les exemples ci-dessous par le nom de votre secret. Pour plus d’informations sur les secrets, consultez « [Utilisation de secrets dans GitHub Actions](/fr/enterprise-cloud@latest/actions/security-guides/using-secrets-in-github-actions) ».\n\nSi vous utilisez le mot clé `run` pour exécuter votre script Ruby dans vos flux de travail GitHub Actions, vous pouvez stocker la valeur de `GITHUB_TOKEN` en tant que variable d’environnement. Votre script peut accéder à la variable d’environnement en tant que `ENV['VARIABLE_NAME']`.\n\nPar exemple, cette étape de workflow stocke `GITHUB_TOKEN` dans une variable d’environnement appelée `TOKEN` :\n\n```yaml\n- name: Run script\n  env:\n    TOKEN: ${{ secrets.GITHUB_TOKEN }}\n  run: |\n    ruby .github/actions-scripts/use-the-api.rb\n```\n\nLe script qu’exécute le workflow utilise `ENV['TOKEN']` pour l’authentification :\n\n```ruby copy\nrequire 'octokit'\n\noctokit = Octokit::Client.new(access_token: ENV['TOKEN'])\n```\n\n### Instanciation sans authentification\n\nVous pouvez utiliser l’API REST sans authentification, mais vous aurez une limite de débit inférieure et vous ne pourrez pas utiliser certains points de terminaison. Pour créer une instance de `Octokit` sans authentification, ne passez pas l’option `access_token`.\n\n```ruby copy\nrequire 'octokit'\n\noctokit = Octokit::Client.new\n```\n\n## Faire des requêtes\n\nOctokit prend en charge plusieurs façons de créer des requêtes. Vous pouvez utiliser la méthode `request` pour créer des requêtes si vous connaissez le verbe HTTP et le chemin du point de terminaison. Vous pouvez utiliser la méthode `rest` si vous souhaitez tirer parti de l’autocomplétion dans votre IDE et de la saisie. Pour les points de terminaison paginés, vous pouvez utiliser la méthode `paginate` pour demander plusieurs pages de données.\n\n### Utilisation de la méthode `request` pour créer des requêtes\n\nPour utiliser la méthode `request` pour créer des requêtes, passez la méthode HTTP et le chemin comme premier argument. Passez tous les paramètres de corps, de requête ou de chemin sous forme de hachage en tant que deuxième argument. Par exemple, pour créer une requête `GET` dans `/repos/{owner}/{repo}/issues` et passer les paramètres `owner`, `repo` et `per_page` :\n\n```ruby copy\noctokit.request(\"GET /repos/{owner}/{repo}/issues\", owner: \"github\", repo: \"docs\", per_page: 2)\n```\n\nLa méthode `request` passe automatiquement l’en-tête `Accept: application/vnd.github+json`. Pour transmettre des en-têtes supplémentaires ou un en-tête `Accept` différent, ajoutez une option `headers` au hachage transmis en tant que deuxième argument. La valeur de l’option `headers` est un hachage dont les clés sont les noms des en-têtes et les valeurs les valeurs des en-têtes. Par exemple, pour envoyer un en-tête `content-type` avec la valeur de `text/plain` :\n\n```ruby copy\noctokit.request(\"POST /markdown/raw\", text: \"Hello **world**\", headers: { \"content-type\" => \"text/plain\" })\n```\n\n### Utilisation des méthodes d'endpoint `rest` pour effectuer des requêtes\n\nChaque point de terminaison d’API REST a une méthode de point de terminaison `rest` associée dans Octokit. Ces méthodes appliquent généralement l’autocomplétion dans votre IDE pour des raisons pratiques. Vous pouvez passer n’importe quel paramètre en tant code de hachage à la méthode.\n\n```ruby copy\noctokit.rest.issues.list_for_repo(owner: \"github\", repo: \"docs\", per_page: 2)\n```\n\n### Création de requêtes paginées\n\nSi le point de terminaison est paginé et que vous souhaitez extraire plusieurs pages de résultats, vous pouvez utiliser la méthode `paginate`.\n`paginate` récupère la page de résultats suivante jusqu’à atteindre la dernière page, puis retourne tous les résultats sous la forme d’un tableau. Certains points de terminaison renvoient des résultats paginés sous forme de tableau dans un objet, plutôt que de renvoyer les résultats paginés sous forme de tableau.\n`paginate` retourne toujours un tableau d’éléments même si le résultat brut était un objet.\n\nPar exemple, l’exemple suivant récupère tous les problèmes du dépôt `github/docs`. Bien qu’elle demande 100 incidents à la fois, la fonction ne renvoie pas de résultat tant que la dernière page de données n’est pas atteinte.\n\n```ruby copy\nissue_data = octokit.paginate(\"GET /repos/{owner}/{repo}/issues\", owner: \"github\", repo: \"docs\", per_page: 100)\n```\n\nLa méthode `paginate` accepte un bloc facultatif, que vous pouvez utiliser pour traiter chaque page de résultats. Cela vous permet de collecter uniquement les données souhaitées à partir de la réponse. Par exemple, l’exemple suivant continue d’extraire les résultats jusqu’à ce qu’un problème incluant « test » dans le titre soit retourné. Pour les pages de données retournées, seuls le titre et l'auteur de l'issue sont stockés.\n\n```ruby copy\nissue_data = octokit.paginate(\"GET /repos/{owner}/{repo}/issues\", owner: \"github\", repo: \"docs\", per_page: 100) do |response, done|\n  response.data.map do |issue|\n    if issue.title.include?(\"test\")\n      done.call\n    end\n    { title: issue.title, author: issue.user.login }\n  end\nend\n```\n\nAu lieu d’extraire tous les résultats à la fois, vous pouvez utiliser `octokit.paginate.iterator()` pour itérer au sein d’une seule page à la fois. Par exemple, l’exemple suivant extrait une page de résultats à la fois et traite chaque objet de la page avant d’extraire la page suivante. Une fois qu’un problème qui inclut « test » dans le titre est atteint, le script arrête l’itération et retourne le titre du problème et l’auteur du problème de chaque objet qui a été traité. L’itérateur est la méthode la plus efficace en mémoire pour extraire des données paginées.\n\n```ruby copy\niterator = octokit.paginate.iterator(\"GET /repos/{owner}/{repo}/issues\", owner: \"github\", repo: \"docs\", per_page: 100)\nissue_data = []\nbreak_loop = false\niterator.each do |data|\n  break if break_loop\n  data.each do |issue|\n    if issue.title.include?(\"test\")\n      break_loop = true\n      break\n    else\n      issue_data << { title: issue.title, author: issue.user.login }\n    end\n  end\nend\n```\n\nVous pouvez également utiliser la méthode `paginate` avec les méthodes de point de terminaison `rest`. Transmettez la méthode de point de terminaison `rest` en tant que premier argument et tous les paramètres comme deuxième argument.\n\n```ruby copy\niterator = octokit.paginate.iterator(octokit.rest.issues.list_for_repo, owner: \"github\", repo: \"docs\", per_page: 100)\n```\n\nPour plus d’informations sur la pagination, consultez [Utilisation de la pagination dans l’API REST](/fr/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api).\n\n## Interception des erreurs\n\n### Capture de toutes les erreurs\n\nParfois, l’API REST GitHub retourne une erreur. Par exemple, vous obtenez une erreur si votre jeton d’accès a expiré ou si vous avez omis un paramètre obligatoire. Octokit.rb retente automatiquement la demande quand il obtient une erreur autre que `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found` et `422 Unprocessable Entity`. Si une erreur d’API se produit même après plusieurs tentatives, Octokit.rb lève une erreur qui inclut le code d’état HTTP de la réponse (`response.status`) et les en-têtes de réponse (`response.headers`). Vous devez gérer ces erreurs dans votre code. Par exemple, vous pouvez utiliser un bloc try/catch pour intercepter les erreurs :\n\n```ruby copy\nbegin\nfiles_changed = []\n\niterator = octokit.paginate.iterator(\"GET /repos/{owner}/{repo}/pulls/{pull_number}/files\", owner: \"github\", repo: \"docs\", pull_number: 22809, per_page: 100)\niterator.each do | data |\n    files_changed.concat(data.map {\n      | file_data | file_data.filename\n    })\n  end\nrescue Octokit::Error => error\nif error.response\nputs \"Error! Status: #{error.response.status}. Message: #{error.response.data.message}\"\nend\nputs error\nend\n```\n\n### Gestion des codes d’erreur prévus\n\nParfois, GitHub utilise un code d’état 4xx pour indiquer une réponse de non-erreur. Si le point de terminaison que vous utilisez le fait, vous pouvez ajouter une gestion supplémentaire pour des erreurs spécifiques. Par exemple, le point de terminaison `GET /user/starred/{owner}/{repo}` retourne une erreur `404` si le dépôt n’a pas d’étoile. L’exemple suivant utilise la réponse `404` pour indiquer que le référentiel n’est pas marqué d’étoile, tous les autres codes d’erreur sont traités comme des erreurs.\n\n```ruby copy\nbegin\noctokit.request(\"GET /user/starred/{owner}/{repo}\", owner: \"github\", repo: \"docs\")\nputs \"The repository is starred by me\"\nrescue Octokit::NotFound => error\nputs \"The repository is not starred by me\"\nrescue Octokit::Error => error\nputs \"An error occurred while checking if the repository is starred: #{error&.response&.data&.message}\"\nend\n```\n\n### Gestion des erreurs de limite de débit\n\nSi vous recevez une erreur de limite de débit, vous pouvez retenter votre demande après avoir attendu. Quand votre taux est limité, GitHub répond avec une erreur `403 Forbidden` et la valeur d’en-tête de réponse `x-ratelimit-remaining` sera `\"0\"`. Les en-têtes de réponse incluent un en-tête `x-ratelimit-reset`, qui vous indique l’heure à laquelle la fenêtre de limite de débit actuelle est réinitialisée, en secondes d’époque UTC. Vous pouvez retenter votre demande après l’heure spécifiée par `x-ratelimit-reset`.\n\n```ruby copy\ndef request_retry(route, parameters)\n begin\n response = octokit.request(route, parameters)\n return response\n rescue Octokit::RateLimitExceeded => error\n reset_time_epoch_seconds = error.response.headers['x-ratelimit-reset'].to_i\n current_time_epoch_seconds = Time.now.to_i\n seconds_to_wait = reset_time_epoch_seconds - current_time_epoch_seconds\n puts \"You have exceeded your rate limit. Retrying in #{seconds_to_wait} seconds.\"\n sleep(seconds_to_wait)\n retry\n rescue Octokit::Error => error\n puts error\n end\n end\n\n response = request_retry(\"GET /repos/{owner}/{repo}/issues\", owner: \"github\", repo: \"docs\", per_page: 2)\n```\n\n## Utilisation de la réponse\n\nLa méthode `request` retourne un objet de réponse si la demande a réussi. L’objet de réponse contient `data` (le corps de la réponse retourné par le point de terminaison), `status` (le code de réponse HTTP), `url` (l’URL de la requête) et `headers` (un code de hachage contenant les en-têtes de réponse). Sauf indication contraire, le corps de réponse est au format JSON. Certains points de terminaison ne retournent pas de corps de réponse, auquel cas, la propriété `data` est omise.\n\n```ruby copy\nresponse = octokit.request(\"GET /repos/{owner}/{repo}/issues/{issue_number}\", owner: \"github\", repo: \"docs\", issue_number: 11901)\n puts \"The status of the response is: #{response.status}\"\n puts \"The request URL was: #{response.url}\"\n puts \"The x-ratelimit-remaining response header is: #{response.headers['x-ratelimit-remaining']}\"\n puts \"The issue title is: #{response.data['title']}\"\n```\n\nDe même, la méthode `paginate` retourne un objet de réponse. Si `request` a réussi, l’objet `response` contient des données, un état, une URL et des en-têtes.\n\n```ruby copy\nresponse = octokit.paginate(\"GET /repos/{owner}/{repo}/issues\", owner: \"github\", repo: \"docs\", per_page: 100)\nputs \"#{response.data.length} issues were returned\"\nputs \"The title of the first issue is: #{response.data[0]['title']}\"\n```\n\n## Exemple de script\n\nVoici un exemple de script complet qui utilise Octokit.rb. Le script importe `Octokit` et crée une nouvelle instance `Octokit`. Si vous souhaitez vous authentifier avec une GitHub App au lieu d’un personal access token, vous devez importer et instancier `App` à la place de `Octokit`. Pour plus d’informations, consultez [Authentification avec une GitHub App](#authenticating-with-a-github-app) dans ce guide.\n\nLa fonction `get_changed_files` obtient tous les fichiers modifiés pour une pull request. La fonction `comment_if_data_files_changed` appelle la fonction `get_changed_files`. Si l’un des fichiers modifiés par la demande de tirage inclut `/data/` dans le chemin, la fonction commente la demande de tirage.\n\n```ruby copy\nrequire \"octokit\"\n\n octokit = Octokit::Client.new(access_token: \"YOUR-TOKEN\")\n\n def get_changed_files(octokit, owner, repo, pull_number)\n files_changed = []\n\n begin\n iterator = octokit.paginate.iterator(\"GET /repos/{owner}/{repo}/pulls/{pull_number}/files\", owner: owner, repo: repo, pull_number: pull_number, per_page: 100)\n iterator.each do | data |\n     files_changed.concat(data.map {\n       | file_data | file_data.filename\n     })\n   end\n rescue Octokit::Error => error\n if error.response\n puts \"Error! Status: #{error.response.status}. Message: #{error.response.data.message}\"\n end\n puts error\n end\n\n files_changed\n end\n\n def comment_if_data_files_changed(octokit, owner, repo, pull_number)\n changed_files = get_changed_files(octokit, owner, repo, pull_number)\n\n if changed_files.any ? {\n   | file_name | /\\/data\\//i.match ? (file_name)\n }\n begin\n comment = octokit.create_pull_request_review_comment(owner, repo, pull_number, \"It looks like you changed a data file. These files are auto-generated. \\n\\nYou must revert any changes to data files before your pull request will be reviewed.\")\n comment.html_url\n rescue Octokit::Error => error\n if error.response\n puts \"Error! Status: #{error.response.status}. Message: #{error.response.data.message}\"\n end\n puts error\n end\n end\n end\n\n# Example usage\nowner = \"github\"\nrepo = \"docs\"\npull_number = 22809\ncomment_url = comment_if_data_files_changed(octokit, owner, repo, pull_number)\n\nputs \"A comment was added to the pull request: #{comment_url}\"\n```\n\n> \\[!NOTE]\n> Il s’agit simplement d’un exemple de base. Dans la pratique, vous pouvez utiliser la gestion des erreurs et les examens conditionnelles pour gérer différents scénarios.\n\n## Étapes suivantes\n\nPour en savoir plus sur l’utilisation de l’API REST GitHub et Octokit.rb, explorez les ressources suivantes :\n\n* Pour en savoir plus sur Octokit.rb, consultez [la documentation Octokit.rb](https://github.com/octokit/octokit.rb/#readme).\n* Pour obtenir des informations détaillées sur les points de terminaison d’API REST disponibles de GitHub, y compris leurs structures de requête et de réponse, consultez [documentation de l’API REST GitHub](/fr/enterprise-cloud@latest/rest)."}