Freigeben über

Pipelinezwischenspeicherung

Azure DevOps Services

Die Pipelinezwischenspeicherung kann dazu beitragen, die Buildzeit zu reduzieren, indem heruntergeladene Abhängigkeiten aus früheren Ausführungen wiederverwendet werden, ohne dass dieselben Dateien neu erstellt oder erneut heruntergeladen werden müssen. Dies ist besonders hilfreich in Szenarien, in denen dieselben Abhängigkeiten zu Beginn jeder Ausführung wiederholt heruntergeladen werden. Dies ist oft ein zeitaufwendiger Prozess mit Hunderten oder Tausenden von Netzwerkaufrufen.

Die Zwischenspeicherung ist am effektivsten, wenn die zum Wiederherstellen und Speichern des Caches erforderliche Zeit kleiner ist als die Zeit, die zum Erneuten Generieren der Dateien benötigt wird. In einigen Fällen bietet die Zwischenspeicherung jedoch möglicherweise keine Leistungsvorteile und wirkt sich sogar negativ auf die Buildzeit aus. Es ist wichtig, Ihr spezifisches Szenario zu bewerten, um festzustellen, ob zwischenspeichern der richtige Ansatz ist.

Anmerkung

Die Pipelinezwischenspeicherung wird für klassische Release-Pipelines nicht unterstützt.

Wann sollten Pipeline-Artefakte verwendet werden im Vergleich zur Pipeline-Zwischenspeicherung?

Pipelinezwischenspeicherung und Pipelineartefakte führen ähnliche Funktionen aus, sind jedoch für verschiedene Szenarien vorgesehen und sollten nicht austauschbar verwendet werden.

  • Verwenden Sie Pipelineartefakte: Wenn Sie bestimmte Dateien verwenden müssen, die von einem Auftrag erstellt wurden, und sie für andere Aufträge freigeben (und diese anderen Aufträge würden wahrscheinlich ohne sie fehlschlagen).

  • Verwenden Sie die Pipelinezwischenspeicherung: Wenn Sie die Erstellungszeit verbessern möchten, indem Sie Dateien aus früheren Ausführungen wiederverwenden (und das Fehlen dieser Dateien die Fähigkeit des Auftrags, ausgeführt zu werden, nicht beeinträchtigt).

Anmerkung

Pipelinezwischenspeicherung und Pipelineartefakte sind kostenlos für alle Ebenen (kostenlos und kostenpflichtig) verfügbar. Weitere Einzelheiten dazu finden Sie unter Artefaktspeichernutzung.

Anforderungen des selbst gehosteten Agenten

Die folgenden ausführbaren Dateien müssen sich in einem Ordner befinden, der in der Umgebungsvariablen PATH aufgeführt ist. Beachten Sie, dass diese Anforderungen nur für selbst gehostete Agents gelten, da gehostete Agents mit der erforderlichen Software vorinstalliert sind.

Archivsoftware / Plattform Fenster Linux (Englisch) Mac
GNU Tar Erforderlich Erforderlich Nein
BSD-Tar Nein Nein Erforderlich
7-Reißverschluss Empfohlen Nein Nein

Cacheaufgabe: Funktionsweise

Zwischenspeichern wird einer Pipeline hinzugefügt, indem der Cache-Vorgang zum steps Abschnitt eines Auftrags hinzugefügt wird.

Während der Pipelineausführung, wenn ein Cache-Schritt auftritt, versucht die Aufgabe, den Cache basierend auf den bereitgestellten Eingaben wiederherzustellen. Wenn kein Cache gefunden wird, wird der Schritt abgeschlossen und der nächste Schritt im Auftrag ausgeführt.

Nachdem alle Schritte im Auftrag erfolgreich ausgeführt wurden, wird automatisch ein spezieller Schritt "Post-Job: Cache" hinzugefügt und für jeden "Cache wiederherstellen"-Schritt ausgelöst, der nicht übersprungen wurde. Dieser Schritt ist für das Speichern des Caches verantwortlich.

Anmerkung

Caches sind unveränderlich. Nachdem ein Cache erstellt wurde, kann der Inhalt nicht mehr geändert werden.

Konfigurieren der Cacheaufgabe

Die Cacheaufgabe weist zwei erforderliche Argumente auf: Pfad und Schlüssel:

  1. pfad: Der Pfad zum Ordner, den Sie zwischenspeichern möchten. Dies kann ein absoluter oder relativer Pfad sein. Relative Pfade werden für $(System.DefaultWorkingDirectory)aufgelöst.

    Tipp

    Sie können vordefinierte Variablen verwenden, um den Pfad zum Ordner zu speichern, den Sie zwischenspeichern möchten. Wildcards werden jedoch nicht unterstützt.

  2. key: Dadurch wird der Bezeichner für den Cache definiert, den Sie wiederherstellen oder speichern möchten. Der Schlüssel besteht aus einer Kombination aus Zeichenfolgenwerten, Dateipfaden oder Dateimustern, wobei jedes Segment durch ein | Zeichen getrennt ist.

    • Zeichenfolgen:
      Ein fester Wert (z. B. der Cache-Name oder ein Tool-Name) oder aus einer Umgebungsvariable (z. B. das aktuelle Betriebssystem oder der Auftragsname).

    • Dateipfade:
      Der Pfad zu einer bestimmten Datei, deren Inhalt hashed wird. Die Datei muss zum Zeitpunkt der Ausführung der Aufgabe vorhanden sein. Jedes Segment, das einem Dateipfad ähnelt, wird als solche behandelt. Seien Sie also vorsichtig, insbesondere bei der Verwendung von Segmenten, die enthalten ., da dies zu Fehlern bei "Datei ist nicht vorhanden" führen kann.

      Tipp

      Um zu vermeiden, dass ein pfadähnliches Zeichenfolgensegment wie ein Dateipfad behandelt wird, schließen Sie es mit doppelten Anführungszeichen um, z. B.: "my.key" | $(Agent.OS) | key.file

    • Dateimuster:
      Eine durch Trennzeichen getrennte Liste von Wildcardmustern im Glob-Stil, die mindestens einer Datei entsprechen müssen. Beispiele

      • **/yarn.lock: alle yarn.lock Dateien unter dem Quellenverzeichnis.
      • */asset.json, !bin/**: alle asset.json Dateien, die sich in einem Verzeichnis unter dem Quellenverzeichnis befinden, mit Ausnahme der dateien im Bin-Verzeichnis .

Der Inhalt einer Datei, die durch einen Dateipfad oder ein Dateimuster identifiziert wird, wird hashed, um einen dynamischen Cacheschlüssel zu generieren. Dies ist nützlich, wenn Ihr Projekt Dateien enthält, die eindeutig identifizieren, was zwischengespeichert wird. Beispielsweise werden Dateien wie package-lock.json, yarn.lock, , Gemfile.lockoder Pipfile.lock häufig in einem Cacheschlüssel referenziert, da sie einen eindeutigen Satz von Abhängigkeiten darstellen. Relative Dateipfade oder Muster werden anhand $(System.DefaultWorkingDirectory) aufgelöst.

  • Beispiel:

Das folgende Beispiel zeigt, wie Yarn-Pakete zwischengespeichert werden:

variables:
  YARN_CACHE_FOLDER: $(Pipeline.Workspace)/s/.yarn

steps:
- task: Cache@2
  inputs:
    key: '"yarn" | "$(Agent.OS)" | yarn.lock'
    restoreKeys: |
       "yarn" | "$(Agent.OS)"
       "yarn"
    path: $(YARN_CACHE_FOLDER)
  displayName: Cache Yarn packages

- script: yarn --frozen-lockfile

In diesem Beispiel besteht der Cacheschlüssel aus drei Teilen: einer statischen Zeichenfolge ("Yarn"), dem Betriebssystem, auf dem der Auftrag ausgeführt wird (da der Cache pro Betriebssystem eindeutig ist) und der Hash der yarn.lock Datei (die die Abhängigkeiten eindeutig identifiziert).

Bei der ersten Ausführung nach dem Hinzufügen der Aufgabe meldet der Cacheschritt einen "Cachefehler", da der durch diesen Schlüssel identifizierte Cache nicht vorhanden ist. Nach dem letzten Schritt wird ein Cache aus den Dateien in $(Pipeline.Workspace)/s/.yarn erstellt und hochgeladen. Bei der nächsten Ausführung meldet der Cacheschritt einen "Cachetreffer", und der Inhalt des Caches wird heruntergeladen und wiederhergestellt.

Bei Verwendung von checkout: self wird das Repository auf $(Pipeline.Workspace)/s ausgecheckt, und Ihr .yarn-Ordner befindet sich wahrscheinlich im Repository selbst.

Anmerkung

Pipeline.Workspace ist der lokale Pfad auf dem Agent, der Ihre Pipeline ausführt, in dem alle Verzeichnisse erstellt werden. Diese Variable hat denselben Wert wie Agent.BuildDirectory. Wenn Sie checkout: self nicht verwenden, stellen Sie sicher, dass Sie die Variable YARN_CACHE_FOLDER so aktualisieren, dass sie auf den Speicherort von .yarn in Ihrem Repository verweist.

Wiederherstellungsschlüssel verwenden

restoreKeys ermöglicht es Ihnen, mehrere genaue Schlüssel oder Schlüsselpräfixe abzufragen. Sie wird als Fallback verwendet, wenn der angegebene key Wert keinen Treffer zurückgibt. Ein Wiederherstellungsschlüssel sucht nach einem Schlüssel nach Präfix und gibt den zuletzt erstellten Cacheeintrag zurück. Dies ist hilfreich, wenn die Pipeline keine genaue Übereinstimmung finden kann, aber trotzdem auf einen teilweisen Cachetreffer zurückgreifen möchte.

Um mehrere Wiederherstellungsschlüssel anzugeben, listen Sie sie in separaten Zeilen auf. Die Reihenfolge, in der die Wiederherstellungsschlüssel ausprobiert werden, ist von oben nach unten.

  • Beispiel:

Hier ist ein Beispiel für die Verwendung von Wiederherstellungsschlüsseln zum Zwischenspeichern von Yarn-Paketen:

variables:
  YARN_CACHE_FOLDER: $(Pipeline.Workspace)/.yarn

steps:
- task: Cache@2
  inputs:
    key: '"yarn" | "$(Agent.OS)" | yarn.lock'
    restoreKeys: |
       yarn | "$(Agent.OS)"
       yarn
    path: $(YARN_CACHE_FOLDER)
  displayName: Cache Yarn packages

- script: yarn --frozen-lockfile

In diesem Beispiel versucht die Cacheaufgabe zunächst, den angegebenen Schlüssel wiederherzustellen. Wenn der Schlüssel im Cache nicht vorhanden ist, wird der erste Wiederherstellungsschlüssel versucht: yarn | $(Agent.OS) Dadurch wird nach Cacheschlüsseln gesucht, die exakt mit diesem Präfix übereinstimmen oder beginnen.

Eine Präfix-Übereinstimmung kann auftreten, wenn sich der Hash der yarn.lock Datei geändert hat. Wenn der Cache beispielsweise den Schlüssel yarn | $(Agent.OS) | old-yarn.lock enthält (bei dem old-yarn.lock ein anderer Hash als der aktuelle yarn.lockHash vorhanden ist), würde dieser Wiederherstellungsschlüssel zu einem teilweisen Cachetreffer führen.

Wenn der erste Wiederherstellungsschlüssel keine Übereinstimmung liefert, ist der nächste Wiederherstellungsschlüssel yarn. Dadurch wird nach einem Cache-Schlüssel gesucht, der mit yarn beginnt. Bei Präfix-Übereinstimmungen gibt der Wiederherstellungsvorgang den zuletzt erstellten Cacheeintrag zurück.

Anmerkung

Eine Pipeline kann mehrere Zwischenspeicherungsaufgaben enthalten, und es gibt kein Speicherlimit für die Zwischenspeicherung. Aufträge und Aufgaben innerhalb derselben Pipeline können auf denselben Cache zugreifen und gemeinsam nutzen.

Wiederherstellungsbedingung verwenden

In einigen Szenarien möchten Sie Schritte abhängig davon ausführen, ob der Cache erfolgreich wiederhergestellt wurde. Sie können z. B. einen Schritt überspringen, der Abhängigkeiten installiert, wenn der Cache wiederhergestellt wurde. Dies kann mithilfe des cacheHitVar Arguments erreicht werden.

Wenn Sie diese Eingabe auf den Namen einer Umgebungsvariable festlegen, wird die Variable auf true gesetzt, wenn ein Cachetreffer auftritt, auf inexact gesetzt, wenn ein Wiederherstellungsschlüssel einen teilweisen Cachetreffer zurückgibt, und auf false gesetzt, wenn kein Cache gefunden wird. Anschließend können Sie in einer Schrittbedingung oder innerhalb eines Skripts auf diese Variable verweisen.

Hier ist ein Beispiel, in dem der install-deps.sh Schritt übersprungen wird, wenn der Cache wiederhergestellt wird:

steps:
- task: Cache@2
  inputs:
    key: mykey | mylockfile
    restoreKeys: mykey
    path: $(Pipeline.Workspace)/mycache
    cacheHitVar: CACHE_RESTORED

- script: install-deps.sh
  condition: ne(variables.CACHE_RESTORED, 'true')

- script: build.sh

Cache-Isolation und Sicherheit

Um die Isolation zwischen Caches aus verschiedenen Pipelines und verschiedenen Verzweigungen sicherzustellen, wird jeder Cache in einem logischen Container gespeichert, der als Bereich bezeichnet wird. Bereiche fungieren als Sicherheitsbegrenzung, die Folgendes garantiert:

  • Aufgaben aus einer Pipeline können nicht auf Caches aus einer anderen Pipeline zugreifen.

  • Aufgaben, die Pull-Anfragen erstellen, können Caches aus dem Zielzweig (für dieselbe Pipeline) lesen, aber keine Caches im Zielzweig schreiben (erstellen).

Wenn während einer Ausführung ein Cacheschritt auftritt, wird der vom Schlüssel identifizierte Cache vom Server angefordert. Der Server sucht dann nach einem Cache mit diesem Schlüssel aus den Bereichen, die für den Auftrag sichtbar sind, und er gibt den Cache zurück (sofern verfügbar). Beim Speichern des Caches (am Ende des Auftrags) wird ein Cache in den Bereich geschrieben, der die Pipeline und die Verzweigung darstellt.

CI, manuelle und geplante Ausführungen

Bereich Lesen Schreiben
Quellzweig Ja Ja
main Filiale Ja Nein
master Filiale Ja Nein

Pull Request-Ausführungen

Bereich Lesen Schreiben
Quellzweig Ja Nein
Zielzweig Ja Nein
Zwischenverzweigung (z. B refs/pull/1/merge) Ja Ja
main Filiale Ja Nein
master Filiale Ja Nein

Pull Request-Forkausführungen

Zweig Lesen Schreiben
Zielzweig Ja Nein
Zwischenverzweigung (z. B refs/pull/1/merge) Ja Ja
main Filiale Ja Nein
master Filiale Ja Nein

Tipp

Da Caches bereits auf ein Projekt, eine Pipeline und eine Verzweigung festgelegt sind, müssen keine Projekt-, Pipeline- oder Verzweigungsbezeichner in den Cacheschlüssel eingefügt werden.

Beispiele

Für Ruby-Projekte mit Bundler setzen Sie die BUNDLE_PATH Umgebungsvariable außer Kraft, um den Pfad festzulegen, in dem Bundler nach Gems sucht.

Beispiel:

variables:
  BUNDLE_PATH: $(Pipeline.Workspace)/.bundle

steps:
- task: Cache@2
  displayName: Bundler caching
  inputs:
    key: 'gems | "$(Agent.OS)" | Gemfile.lock'
    path: $(BUNDLE_PATH)
    restoreKeys: | 
      gems | "$(Agent.OS)"
      gems

Bekannte Probleme und Feedback

Wenn Sie Probleme beim Einrichten der Zwischenspeicherung in Ihrer Pipeline haben, überprüfen Sie die Liste der offenen Probleme im microsoft/azure-pipelines-tasks Repository. Wenn Ihr Problem nicht aufgeführt wird, erstellen Sie ein neues Issue, und geben Sie die erforderlichen Informationen zu Ihrem Szenario an.

Fragen und Antworten

F: Kann ich einen Cache löschen?

A: Das Löschen eines Caches wird nicht unterstützt. Sie können jedoch Treffer für vorhandene Caches vermeiden, indem Sie Ihrem Cache-Schlüssel ein Zeichenfolgenliteral (z. B. version2) hinzufügen. Ändern Sie beispielsweise den folgenden Cacheschlüssel von:

key: 'yarn | "$(Agent.OS)" | yarn.lock'

Folgendermaßen:

key: 'version2 | yarn | "$(Agent.OS)" | yarn.lock'

F: Wann läuft ein Cache ab?

A: Caches laufen nach sieben Tagen ohne Aktivität ab.

F: Wann wird der Cache hochgeladen?

A: Ein Cache wird aus dem angegebenen path erstellt und nach dem letzten Schritt des Auftrags hochgeladen. Weitere Einzelheiten dazu finden Sie im Beispiel.

F: Gibt es ein Limit für die Größe eines Caches?

A: Es gibt keine erzwungene Beschränkung für die Größe einzelner Caches oder die Gesamtcachegröße innerhalb einer Organisation.

Verwandte Inhalte