GitHub -Collector für die API-Erkennung konfigurieren

Vorgehensweise zum Hinzufügen eines GitHub -Datenquellenkollektors zu Ihrer API-Erkennungsfunktion .

Vorbereitende Schritte

Bevor Sie einen API-Erkennungscollector GitHub konfigurieren können, müssen die folgenden Voraussetzungen erfüllt sein:

Sie müssen über ein GitHub -Repository verfügen, das mindestens ein OpenAPI -Referenzdokument enthält.

Eine der folgenden Providerorganisationsrollen ist erforderlich, um Quellen verwalten zu können:

Organisationsadministrator
Eigner
Angepasste Rolle mit der Berechtigung Settings: Manage .

Informationen zu dieser Task

Die API-Erkennung ist ein Add-on für IBM® API Connect , mit dem Sie APIs erkennen und zu Ihrem API-Entwicklungsprozess hinzufügen können. Bevor Sie APIs erkennen können, müssen Sie mindestens einen Datenquellencollector konfigurieren. Diese Collectors werden dann automatisch zur Registerkarte Quellen in der Benutzerschnittstelle von API Manager hinzugefügt, wenn der Collector die ersten OpenAPI -Dokumente an Ihre Provider-Organisation sendet.

Zum Konfigurieren eines API-Erkennungskollektors GitHub erstellen Sie einen Workflow für GitHub -Aktionen in Ihrem GitHub -Repository. Mit diesem Workflow können Ihre OpenAPI -Referenzdokumente automatisch an API Connectgesendet und mit diesem synchronisiert werden. Diese OpenAPI -Dokumente können dann nach Bedarf in API-Entwürfe kopiert werden, um das vollständige Lebenszyklusmanagement in API Managerzu aktivieren.

Hinweis: Wenn eine API mit großen Nutzdaten gesendet wird (z. B. eine komplexe API mit einer Größe von mehr als 1 MB), kann es zu Verzögerungen bei der Erstellung der erkannten API kommen. Es wird empfohlen, keinen weiteren Workflow gleichzeitig auszuführen, bis Sie sehen, dass eine API im API-Erkennungsservice erstellt wurde.

Vorgehensweise

Führen Sie die folgenden Schritte aus, um einen GitHub -Collector zu konfigurieren.

Erstellen Sie ein Verzeichnis .github/workflows in Ihrem Repository auf GitHub (falls dieses Verzeichnis nicht existiert).
Erstellen Sie im Verzeichnis .github/workflows eine Datei für Ihre Workflowaktion, z. B. discover-api.yml.

Kopieren Sie in der Workflowaktionsdatei den folgenden Workflow-Job:

Der folgende YAML enthält den Workflow für den Job run-discovery . Bei einem Push-Commit an das GitHub prüft dieser Job, ob es Änderungen an den angegebenen Dateien oder Ordnern gibt, und wenn ja, sendet er die Git-Differenz der Übertragungen in den Dateien an API Connect. API_FILES kann in API_FOLDERS geändert werden, wenn mindestens ein vollständiger Ordner erkannt werden muss.

name: Sync Discovered API with APIConnect

on: [pull_request, workflow_dispatch, push]

env:
  API_HOST: <host-name>
  PLATFORM_API_PREFIX: <platform-api>
  PROVIDER_ORG: <porg-name>
  API_FILES: <file/files name>

jobs:
  run-discovery:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Difference
      id: difference-output
      run: |
        echo "action_updates=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | xargs)" >> $GITHUB_OUTPUT
    - uses: ibm-apiconnect/apic-discovery-action@main
      id: discover-apis
      with:
        api_host: ${{ env.API_HOST }}
        platform_api_prefix: ${{ env.PLATFORM_API_PREFIX }}
        provider_org: ${{ env.PROVIDER_ORG }}
        api_key: ${{ secrets.apicApikey }}
        if: env.API_FILES
        api_files: ${{ env.API_FILES }}
        else if: env.API_FOLDERS
        api_folders: ${{ env.API_FOLDERS }}
        resync_check: ${{ true }}
        git_diff: ${{ steps.difference-output.outputs.action_updates }}
    - name: Display the action-result
      run: |
        echo "Result of the action: ${{ steps.discover-apis.outputs.action-result }}"
        echo "End"

Beachten Sie, dass Sie optional auch die folgende check_changes_job -Workflowdatei verwenden können. Bei einer Push-Übertragung an das GitHub überprüft dieser Job, ob es Änderungen an den angegebenen Dateien oder Ordnern oder eine Änderung an der Datei discover-api.yml gibt, und wenn ja, sendet der Job die Dateien an API Connect. API_FILES kann in API_FOLDERS geändert werden, wenn mindestens ein vollständiger Ordner erkannt werden muss.

name: Sync Discovered API with APIConnect

on: [pull_request, workflow_dispatch, push]

env:
  API_HOST: <host-name>
  PLATFORM_API_PREFIX: <platform-api>
  PROVIDER_ORG: <porg-name>
  API_FILES: <file/files name>

jobs:
  check_changes_job:
    runs-on: 'ubuntu-20.04'
    # Declare outputs for next jobs
    outputs:
      action_changed: ${{ steps.check_workflow_changed.outputs.action_updates }}
      changed_filename: ${{ steps.changed_filename.outputs.api_file }}
      apifiles_env: ${{ steps.changed_filename.outputs.apifiles_env }}
      folder_changed: ${{ steps.check_apifolders_changed.outputs.folder_updates }}
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 2
    - name: Check Workflow changed
      id: check_workflow_changed
      run: |
        echo "action_updates=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | grep discover-api.yml | xargs)" >> $GITHUB_OUTPUT
    - name: Changed API File Name
      id: changed_filename
      run: |
        echo "api_file=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | xargs)" >> $GITHUB_OUTPUT
        echo "apifiles_env=$(echo $API_FILES)" >> $GITHUB_OUTPUT
    - name: Check API Folders changed
      id: check_apifolders_changed
      run: |
        echo "folder_updates=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | grep $API_FOLDERS | xargs)" >> $GITHUB_OUTPUT
  run-discovery:
    runs-on: ubuntu-latest
    needs: [ check_changes_job ]
    if: ${{ (contains(needs.check_changes_job.outputs.apifiles_env,needs.check_changes_job.outputs.changed_filename)) || (needs.check_changes_job.outputs.action_changed) || (needs.check_changes_job.outputs.folder_changed) }}
    steps:
    - uses: actions/checkout@v4
    - uses: ibm-apiconnect/apic-discovery-action@main
      id: discover-apis
      with:
        api_host: ${{ env.API_HOST }}
        platform_api_prefix: ${{ env.PLATFORM_API_PREFIX }}
        provider_org: ${{ env.PROVIDER_ORG }}
        api_key: ${{ secrets.apicApikey }}
        if: env.API_FILES
        api_files: ${{ env.API_FILES }}
        else if: env.API_FOLDERS
        api_folders: ${{ env.API_FOLDERS }}
        resync_check: ${{ needs.check_changes_job.outputs.action_changed && true || false }}
    - name: Display the action-result
      run: |
        echo "Result of the action: ${{ steps.discover-apis.outputs.action-result }}"

Dabei gilt:

name steht für den Namen Ihres GitHub -Aktionsworkflows.
API_HOST ist der Domänenname der API Connect -Instanz, an die die erkannten APIs gesendet werden. Zum Beispiel us-east-a.apiconnect.automation.ibm.com.
PLATFORM_API_PREFIX hat den Standardwert platform-api. Sie können sie ändern, um sie an Ihre Systemkonfiguration anzupassen, falls sie anders ist.
Wenn INSECURE_SKIP_TLS_VERIFY auf truegesetzt ist, überspringt diese Aktion die Gültigkeitsprüfung für das Serverzertifikat. Diese Aktion kann erforderlich sein, wenn Ihr API Connect -System selbst signierte Zertifikate verwendet. Beachten Sie, dass die Einstellung dieser Aktion auf true Ihre HTTPS -Verbindungen unsicher macht.
PROVIDER_ORG ist der Name der API Connect -Providerorganisation.
API_FILES oder API_FOLDERS gibt an, ob einzelne oder mehrere API-Dateien oder Ordner für die Workflowaktion berücksichtigt werden sollen. Trennen Sie mehrere Dateien oder Ordner durch Kommas voneinander, z. B. mail-api.yaml,my-api.json,APIfolder/pet-exp.json. Die API-Dateien können das Format json oder yaml haben.
resync_check gibt an, ob Änderungen an der Aktion, beispielsweise bei der Ersterstellung, eine Synchronisation der API-Datei auslösen sollen.
git_diff überprüft die Differenz zwischen dem aktuellen und dem vorherigen Commit. Wenn mehrere Dateien in der Übergabe geändert wurden, wird der Arbeitsablauf nur ausgeführt, wenn sich eine oder mehrere der Dateien, die in API_FILES oder API_FOLDERS angegeben sind, geändert haben.
api_key sind die Berechtigungsnachweise, die zum Übertragen von API-Dateien an API Managererforderlich sind. Sie können den API-Schlüssel von dem Benutzer abrufen, der Zugriff auf API Manager zum Veröffentlichen von APIs hat. Informationen zum Abrufen eines API-Schlüssels finden Sie unter Plattform-REST-API-Schlüssel verwalten. Anschließend müssen Sie den API-Schlüssel in einem geheimen GitHub -Schlüssel speichern, der dann von diesem GitHub -Aktionsworkflow verwendet werden kann. In der YAML in diesem Schritt wird die api_key als apicApikeybezeichnet. Wenn Sie also diese YAML wiederverwenden möchten, stellen Sie sicher, dass Sie Ihren geheimen Schlüssel mit demselben Namen erstellen. Informationen zum Speichern von API-Schlüsseln als geheime Schlüssel in GitHub -Aktionen finden Sie unter Using secrets in GitHub Actions in der GitHub -Dokumentation.

Weitere Informationen zu apic-discovery-actionund dessen Verwendung finden Sie unter apic-discovery-action und apic-discovery-test unter github.com. Diese API Connect -Ressourcen enthalten Arbeitsbeispiele mit einem Testrepository.

Schreiben Sie die Workflowdatei in einem Zweig in Ihrem GitHub -Repository fest.
Durch das Festschreiben der Workflowdatei wird ein Ereignis push ausgelöst und der Synchronisationsworkflow mit API Connectausgeführt.
Klicken Sie in der Benutzerschnittstelle von API Manager auf das Symbol Erkennen und anschließend auf die Registerkarte Quellen , um Ihren GitHub -Collector anzuzeigen.
Quellen können den folgenden Status haben:
- Aktiviert -Die Quelle ist aktiviert und wird entsprechend ihrer Konfiguration mit dem Collector synchronisiert.
- Inaktiviert -Die Quelle ist inaktiviert und API Connect akzeptiert keine Dateien vom Collector. Dieser Status wird vom Erkennungsservice festgelegt, wenn eine Erkennungsoperation fehlschlägt.
- Fehlerhaft -Der Quellencollector ist nicht verfügbar.
- Angehalten -Die Quelle wurde angehalten und API Connect akzeptiert keine Dateien vom Collector.
Optional: Sie können auf das Symbol Optionen neben einer Quelle klicken, um ihren Status zu ändern.
- Collector anhalten -Zum Anhalten der Quelle.
- Collector löschen -Zum Löschen der Quelle aus der Benutzerschnittstelle von API Manager . Die externen Quellendateien werden nicht gelöscht.
- Resume collector -Zum erneuten Starten einer angehaltenen oder inaktivierten Quelle.
Optional: Sie können in der Tabellenkopfzeile auf das Symbol Spalten verwalten klicken, um die Reihenfolge und Ansicht der Spalten zu ändern.

Ergebnisse

Ihr GitHub -Datenquellencollector ist jetzt für die Synchronisation mit API Connectbereit. Wenn der Collector die ersten OpenAPI Dokumente an Ihre Providerorganisation sendet, wird der Collector auf der Registerkarte Quellen im Abschnitt Erkennen von API Manageraufgelistet. Ein GitHub -Collector übergibt Aktualisierungen nur dann an API Connect , wenn ein Unterschied aufgrund eines Festschreibungs-oder PR-Ereignisses in der ursprünglichen Datenquelle erkannt wird.

Nächste Schritte

Sie können auf die Registerkarte APIs im Bereich Erkennen der Benutzerschnittstelle von API Manager klicken und den API-Datenverkehr in Ihrer GitHub -Quelle überprüfen. Weitere Informationen finden Sie unter Erkannte APIs überprüfen.