Erste Schritte mit der REST-API

Um eine Anforderung mithilfe von JavaScript auszuführen, kannst du „Octokit.js“ verwenden. Weitere Informationen findest du unter Skripterstellung mit der REST-API und JavaScript.

Erstelle zunächst eine Instanz von Octokit. Lege die Basis-URL auf http(s)://HOSTNAME/api/v3 fest. Ersetze [hostname] durch den Namen von deine GitHub Enterprise Server-Instanz.

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
});

Verwende dann die request-Methode, um Anforderungen auszuführen. Übergib die HTTP-Methode und den Pfad als erstes Argument.

await octokit.request("GET /octocat", {});

Um dich bei der Octokit.js-Bibliothek zu authentifizieren, kannst du dein Token übergeben, wenn du eine Instanz von Octokit erstellst. Ersetze YOUR-TOKEN durch dein Token. Replace [hostname] durch den Namen von deine GitHub Enterprise Server-Instanz.

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN',
});

Du kannst auch das Schlüsselwort run verwenden, um deine JavaScript-Skripts in deinen GitHub Actions-Workflows auszuführen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

GitHub empfiehlt, dass du dich mit dem integrierten GITHUB_TOKEN authentifizierst, anstatt ein Token zu erstellen. Wenn das nicht möglich ist, speichere dein Token als Geheimnis, und ersetze GITHUB_TOKEN im folgenden Beispiel durch den Namen deines Geheimnisses. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu Geheimnissen findest du unter Verschlüsselte Geheimnisse.

Der nachstehende Beispielworkflow übernimmt folgende Aufgaben:

1. Überprüfen des Repositoryinhalts
2. Einrichten von Node.js
3. Installieren von octokit
4. Speichern des Werts von GITHUB_TOKEN als Umgebungsvariable namens TOKEN und Ausführen des Skripts .github/actions-scripts/use-the-api.mjs, das auf diese Umgebungsvariable als process.env.TOKEN zugreifen kann

Beispielworkflow:

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Check out repo content
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          node .github/actions-scripts/use-the-api.mjs

JavaScript-Beispielskript mit dem Dateipfad .github/actions-scripts/use-the-api.mjs:

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN,
});

await octokit.request("GET /octocat", {});

Anstatt dein Skript in einer separaten Datei zu speichern und das Skript von deinem Workflow aus auszuführen, kannst du die actions/github-script-Aktion verwenden, um ein Skript auszuführen. Weitere Informationen findest du in der actions/github-Infodatei.

jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.request('GET /octocat', {})

Die Octokit.js-Bibliothek übergibt automatisch den Accept: application/vnd.github+json-Header. Um zusätzliche Header oder einen anderen Accept-Header zu übergeben, füge dem Objekt eine headers-Eigenschaft hinzu, die als zweites Argument an die request-Methode übergeben wird. Der Wert der Eigenschaft headers ist ein Objekt mit den Headernamen als Schlüssel und den Headerwerten als Werte. Es folgt ein Beispiel zum Senden eines content-type-Headers mit dem Wert text/plain:

await octokit.request("GET /octocat", {
  headers: {
    "content-type": "text/plain",
  },
});

Wenn du eine Anforderung mit Octokit.js stellst, werden alle Parameter (einschließlich der Pfadparameter) in einem Objekt als zweites Argument an die Methode request übergeben. Um Issues aus dem octocat/Spoon-Knife Repository abzurufen, gib owner als octocat und repo als Spoon-Knife an.

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife"
});

Wenn du eine Anforderung mit Octokit.js stellst, werden alle Parameter (einschließlich der Abfrageparameter) in einem Objekt als zweites Argument an die Methode request übergeben.

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
  sort: "updated",
  direction: "asc",
});

Wenn du eine Anforderung mit „Octokit.js“ stellst, werden alle Parameter (einschließlich der Textparameter) in einem Objekt als zweites Argument an die Methode request übergeben.

await octokit.request("POST /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  title: "Created with the REST API",
  body: "This is a test issue created by the REST API",
});

Wenn du eine Anforderung mit „Octokit.js“ ausführst, gibt die Methode request eine Zusage zurück. Wenn die Anforderung erfolgreich war, wird die Zusage in ein Objekt aufgelöst, das den HTTP-Statuscode der Antwort (status) und die Antwortheader (headers) enthält. Wenn ein Fehler auftritt, wird die Zusage in ein Objekt aufgelöst, das den HTTP-Statuscode der Antwort (status) und die Antwortheader (response.headers) enthält.

Du kannst einen try/catch-Block verwenden, um einen eventuell auftretenden Fehler abzufangen. Wenn die Anforderung im folgenden Skript beispielsweise erfolgreich ist, protokolliert das Skript den Statuscode und den Wert des x-ratelimit-remaining-Headers. War die Anforderung nicht erfolgreich, protokolliert das Skript den Statuscode, den Wert des x-ratelimit-remaining-Headers und die Fehlermeldung.

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
});

Du kannst zum Beispiel den Titel und die Autoren-ID für jedes Issue abrufen:

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}