Publikowanie wydań APK

Jak działa publikacja

Utwórz w API Nomid wieloczęściową sesję przesyłania, wyślij bajty APK bezpośrednio do S3 za pomocą krótkotrwałych adresów URL poszczególnych części, sfinalizuj sesję i odpytuj o końcowy wynik przetwarzania.

LIBRARY_MANAGE obejmuje teraz przesyłanie APK i zarządzanie aplikacjami, w tym odczyt, edycję, ukrywanie i przywracanie aplikacji oraz wydań. Publiczne API dla plików, kontaktów i innych zasobów biblioteki nadal nie są dostępne. Uprawnienie nie zapewnia przypisywania zasad, poleceń dla urządzeń, aprowizacji ani administrowania kontem.

Odczytuj aplikacje biblioteki firmy i zarządzaj nimi oraz publikuj podpisane wydania APK. LIBRARY_MANAGE to wrażliwe uprawnienie obejmujące całą firmę, dotyczące przesyłania APK i zarządzania aplikacjami. Nie zapewnia przypisywania zasad, poleceń dla urządzeń, aprowizacji ani operacji na koncie.

Ukończona publikacja umieszcza wydanie w bibliotece i może uruchomić istniejącą dystrybucję dla zasad korzystających z jego aplikacji i ścieżki. Nie potwierdza, że jakiekolwiek urządzenie zainstalowało to wydanie.

Zanim zaczniesz

• Utwórz dedykowany klucz API z uprawnieniem LIBRARY_MANAGE. Użytkownik Portalu nadający to uprawnienie potrzebuje API_KEY_MANAGE, nieograniczonego zakresu zasad firmy oraz LIBRARY_VIEW i LIBRARY_EDIT. Uprawnienie wrażliwe jest domyślnie odznaczone; istniejące klucze nie otrzymują go automatycznie.
• Przyznaj klucz wyłącznie zaufanej automatyzacji, która potrzebuje tych operacji na bibliotece w całej firmie. LIBRARY_MANAGE zezwala na przesyłanie APK i zarządzanie aplikacjami, w tym na dostęp do sesji przesyłania rozpoczętych przez inne autoryzowane klucze firmy lub użytkowników; przechowuj klucz w magazynie sekretów CI oraz obróć go lub unieważnij, gdy zmieni się dostęp.
• Do przykładowego skryptu przesyłającego użyj Pythona 3.11 lub nowszego. Przed przesłaniem zbuduj i podpisz APK właściwą tożsamością podpisującą oraz odpowiednim kodem wersji Androida. API nie podpisuje plików APK ani nie publikuje w Google Play.
• Wysyłaj X-API-Key do API Nomid. Zweryfikowany klucz wskazuje firmę; żądania nie zawierają parametru najemcy ani firmy. Do publikacji APK nie jest potrzebne uprawnienie DEVICES_READ ani POLICIES_READ.

Punkty końcowe

https://api.nomid.tech/emm/api/v1

Wszystkie osiem poniższych tras wymaga X-API-Key z uprawnieniem LIBRARY_MANAGE; sesja przesyłania należy do firmy przypisanej do klucza.

Kolejność przesyłania

1. POST /check z filename, rzeczywistym dodatnim rozmiarem w bajtach, dozwolonym mime oraz SHA-256 pliku APK. Sprawdź allowed i reason; mogą też wystąpić duplicateOf i existingSessionId.
2. POST /start z tymi samymi polami. Zapisz zwrócone sessionId i partSize w bezpieczny sposób, aby to uruchomienie można było wznowić po przerwaniu.
3. Dla każdej brakującej części wyślij POST /parts/sign z sessionId i partNumber od 1 do 10000.
4. Podziel plik na kolejne fragmenty po partSize bajtów; tylko ostatni fragment może być krótszy. Wyślij PUT każdego fragmentu pod jego podpisany adres URL, używając requiredHeaders, a następnie zachowaj nagłówek odpowiedzi ETag dokładnie w zwróconej postaci.
5. POST /complete z sessionId, każdą parą partNumber/etag i opcjonalnymi tracks. Finalizacja uruchamia przetwarzanie APK w tle; natychmiastowa odpowiedź nadal może wskazywać processing.
6. Wykonuj GET na punkcie końcowym status z identyfikatorem sesji, aż status zapisany małymi literami przyjmie wartość completed lub failed. Odpowiedzi completed zawierają app; odpowiedzi failed zawierają errorMessage. Pozostałe stany nie oznaczają powodzenia publikacji.

Rozmiar musi być większy od zera i mieścić się w skonfigurowanym limicie przesyłania. mime to application/vnd.android.package-archive lub application/octet-stream; sha256 to skrót szesnastkowy bajtów APK złożony z 64 znaków, zapisany małymi literami. Obowiązują terminy ważności sesji i podpisanych adresów URL.

Podpisany adres URL dotyczy S3, a nie API Nomid: z PUT wysyłaj wyłącznie requiredHeaders, nigdy X-API-Key. Nie zapisuj podpisanego adresu URL w logach. Jeśli wygaśnie, podpisz tę część ponownie.

Przykłady żądań i odpowiedzi

Te przykłady pokazują nazwy pól i wartości statusu zapisane małymi literami. Identyfikatory, skrót, czas, rozmiar części, wartości ETag i adres URL są poglądowe; użyj wartości zwróconych dla własnej sesji.

{
  "filename": "app-release.apk",
  "size": 33554432,
  "mime": "application/vnd.android.package-archive",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

{
  "allowed": true,
  "recommendedPartSize": 16777216
}

{
  "sessionId": "123e4567-e89b-12d3-a456-426614174000",
  "partSize": 16777216,
  "expiresAt": "2026-10-28T12:00:00Z"
}

{
  "sessionId": "123e4567-e89b-12d3-a456-426614174000",
  "partNumber": 1
}

{
  "url": "https://<presigned-part-url>",
  "requiredHeaders": {}
}

{
  "status": "uploading",
  "partSize": 16777216,
  "parts": [{ "partNumber": 1, "etag": "\"example-etag\"" }]
}

{
  "sessionId": "123e4567-e89b-12d3-a456-426614174000",
  "parts": [
    { "partNumber": 1, "etag": "\"example-etag-1\"" },
    { "partNumber": 2, "etag": "\"example-etag-2\"" }
  ],
  "tracks": ["prod"]
}

{
  "status": "processing",
  "sessionId": "123e4567-e89b-12d3-a456-426614174000"
}

requiredHeaders może zawierać nagłówki wymagane przez podpis S3. Zastosuj zwróconą mapę dokładnie, wraz ze wszystkimi wartościami, i zachowaj nagłówek odpowiedzi ETag z każdego udanego PUT.

Kontrole przesyłania

Każde przesłanie jest kontrolowane, zanim powstanie jego wydanie: sprawdzane są podpis i manifest APK, wcześniejsze wydania tego samego pakietu w Twojej firmie oraz urządzenia firmy (ich poziomy API Androida oraz zainstalowane na nich aplikacje wraz z certyfikatami podpisu). Wynikiem jest raport kontroli, który możesz odczytać z API.

Kontrole tylko zgłaszają ustalenia. Ustalenia są zapisywane i zwracane, a przesyłanie nadal się kończy; jedynie VERSION_CODE_CONFLICT odrzuca przesłanie. Ustalenie o severity ERROR opisuje APK, którego urządzenia mogą odmówić instalacji lub aktualizacji; WARNING opisuje APK, który się instaluje, ale wiąże się z ryzykiem wartym uwagi. Żadne z nich nie zatrzymuje przesyłania.

Ukończone przesłanie zawiera checkReport w odpowiedzi GET /status oraz w odpowiedzi POST /complete, gdy zwraca ona zakończoną sesję (na przykład przy powtórzonym wywołaniu). Przesłanie odrzucone przez kontrolę ma status failed i również zawiera checkReport. Raportu nie ma, dopóki przesyłanie jest przetwarzane, ani wtedy, gdy przesyłanie nie powiodło się z innego powodu. errorMessage nieudanego przesłania ma ogólną treść, więc aby dowiedzieć się, dlaczego kontrola je odrzuciła, odczytaj w checkReport ustalenia z blocking równym true.

Wydania zwracane przez trasy wersji biblioteki (lista wersji i pojedyncza wersja, opisane w przewodniku po aplikacjach biblioteki) zawierają checkSummary: status najnowszego raportu, errorCount (ustalenia ERROR) i warningCount (ustalenia WARNING). Dla wydań przesłanych przed wprowadzeniem kontroli ma wartość null. Trasa check-report z powyższej tabeli zwraca pełny raport wydania w tym samym kształcie co checkReport i odpowiada 404, gdy wydanie go nie ma. Podobnie jak trasy przesyłania wymaga X-API-Key z uprawnieniem LIBRARY_MANAGE.

Pola raportu

• status: PASSED (brak ustaleń), WARNINGS (wydanie zostało utworzone i ma ustalenia, w tym ustalenia ERROR, które nie zablokowały przesłania) lub BLOCKED (ustalenie zatrzymało przesyłanie i nie utworzono wydania).
• findings: najpierw ustalenia ERROR. Każde z nich zawiera code, severity (ERROR lub WARNING), params, blocking oraz affectedDeviceCount, gdy ustalenie dotyczy urządzeń. blocking ma wartość true wyłącznie dla ustalenia, które zatrzymało przesyłanie.
• params: wartości odczytane z przesłanego APK lub z wydań Twojej firmy, takie jak wersje, poziomy SDK, nazwy uprawnień i ABI oraz odciski certyfikatów. Jego klucze zależą od kodu.
• affectedDeviceCount: liczba urządzeń Twojej firmy, których dotyczy ustalenie. Dla MIN_SDK_ABOVE_FLEET i TARGET_SDK_TOO_LOW params.scope ma wartość INSTALLED, gdy zlicza urządzenia z zainstalowanym pakietem, lub COMPANY, gdy żadne urządzenie go nie ma i zliczane są wszystkie urządzenia firmy.
• checkerVersion identyfikuje zestaw kontroli, który wygenerował raport. createdAt to czas zapisania raportu w UTC.

Kody kontroli

Kody są stałe: mogą pojawiać się nowe, a istniejące nie są zmieniane. Odczytuj severity i blocking z każdego ustalenia, a nie z tej tabeli.

Przykłady raportu kontroli

Pierwszy przykład to odpowiedź GET status dla ukończonego przesłania z ustaleniami; inne pola, takie jak app, zostały pominięte. Drugi to nieudane przesłanie odrzucone przez kontrolę. Identyfikatory, liczby, odciski i czasy są poglądowe.

{
  "status": "completed",
  "sessionId": "123e4567-e89b-12d3-a456-426614174000",
  "checkReport": {
    "status": "WARNINGS",
    "findings": [
      {
        "code": "SIGNING_KEY_CHANGED",
        "severity": "ERROR",
        "params": {
          "installedCertSha1": ["0123456789abcdef0123456789abcdef01234567"],
          "newCertSha1": ["89abcdef0123456789abcdef0123456789abcdef"]
        },
        "affectedDeviceCount": 2,
        "blocking": false
      },
      {
        "code": "MIN_SDK_ABOVE_FLEET",
        "severity": "WARNING",
        "params": { "minSdk": 28, "scope": "INSTALLED" },
        "affectedDeviceCount": 3,
        "blocking": false
      },
      {
        "code": "MISSING_ARM64",
        "severity": "WARNING",
        "params": { "abis": ["armeabi-v7a"] },
        "blocking": false
      }
    ],
    "checkerVersion": "2",
    "createdAt": "2026-11-03T09:30:00Z"
  }
}

{
  "status": "failed",
  "sessionId": "123e4567-e89b-12d3-a456-426614174000",
  "errorMessage": "Upload processing failed",
  "checkReport": {
    "status": "BLOCKED",
    "findings": [
      {
        "code": "VERSION_CODE_CONFLICT",
        "severity": "ERROR",
        "params": { "versionCode": 42 },
        "blocking": true
      }
    ],
    "checkerVersion": "2",
    "createdAt": "2026-11-03T09:30:00Z"
  }
}

{
  "versionCode": 42,
  "environment": "",
  "status": "PUBLISHED",
  "displayName": "Kiosk",
  "displayVersion": "1.4.2",
  "createdAt": "2026-11-03T09:30:00Z",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "fileSizeBytes": 33554432,
  "tracks": ["prod"],
  "checkSummary": { "status": "WARNINGS", "errorCount": 1, "warningCount": 2 }
}

Tracks i ponowienia

Pominięcie tracks oznacza użycie prod. Pierwsze wydanie nowej aplikacji zawsze obejmuje prod, nawet jeśli zażądano innej ścieżki. Kolejne wydania mogą wskazywać jawne nazwy ścieżek o długości do 10 znaków. W tym API nie ma etapu wersji roboczej ani zatwierdzenia.

Zgodna suma kontrolna może wskazać istniejącą aplikację lub wersję, ale nie przypisuje tego wydania do ścieżki zażądanej w tym uruchomieniu. Nie traktuj wyniku duplikatu z /check jako powodzenia publikacji dla nowej ścieżki.

Wznawiaj wyłącznie sesję o identyfikatorze zapisanym podczas tego samego uruchomienia publikacji, z tym samym APK i tymi samymi tracks. Wykonaj GET na punkcie końcowym przesłanych części z tym identyfikatorem sesji, aby użyć ich ponownie. Po niepewnym wyniku /complete odpytaj tę sesję, zanim ponowisz finalizację. Przerwana lub wygasła sesja wymaga nowego przesyłania.

Publikowanie z CI

Na runnerze CI z Linuksem, z Pythonem 3.11 lub nowszym i sha256sum, pobierz skrypt przesyłający napisany w Pythonie z użyciem samej biblioteki standardowej i zweryfikuj jego przypiętą sumę kontrolną przed uruchomieniem. Sprawdź i wersjonuj zweryfikowaną kopię w repozytorium potoku na potrzeby kolejnych uruchomień. Przekaż NOMID_API_KEY przez mechanizm wstrzykiwania sekretów w Twojej platformie CI. Skrypt kończy działanie kodem niezerowym w razie błędu lub przekroczenia limitu czasu.

Pobierz skrypt przesyłający w Pythonie

curl --fail --silent --show-error --output publish_apk.py \
  https://www.nomidmdm.com/developers/publish_apk.py &&
printf '%s  %s\n' '8d9ba2a4432e6e6db05ba2411bfb6bfa85c85a79d1ce480d97e0014f965f12d2' publish_apk.py | sha256sum --check --status &&
python3 publish_apk.py app-release.apk --track prod

Aby wznowić przerwane uruchomienie, jawnie przekaż zapisany identyfikator sesji, z tym samym APK i tymi samymi tracks:

python3 publish_apk.py app-release.apk --track prod \
  --session-id SESSION_ID_FROM_PREVIOUS_RUN

Nie umieszczaj klucza API w poleceniu, repozytorium ani logach; nie włączaj śledzenia powłoki. Nie dopuszczaj podpisanych adresów URL i ich wymaganych nagłówków do logów CI. Powodzenie publikacji i instalacja na urządzeniach to osobne kontrole.

GitHub Actions: publikowanie APK po opublikowaniu wydania

Ten kompletny workflow pobiera już podpisany APK dołączony do wydania GitHub, które go uruchomiło, weryfikuje skrypt przesyłający Nomid i czeka na publikację w bibliotece firmy. Korzysta z zasobu wydania, a nie z artefaktu kompilacji Actions, i nie buduje ani nie podpisuje Twojej aplikacji.

1. Utwórz dedykowany klucz API Nomid z uprawnieniem LIBRARY_MANAGE. W repozytorium GitHub otwórz Settings → Secrets and variables → Actions i dodaj sekret repozytorium o nazwie NOMID_API_KEY zawierający ten klucz. Uprawnienia do urządzeń ani zasad nie są potrzebne.
2. Zapisz poniższy YAML jako .github/workflows/publish-to-nomid.yml w swoim repozytorium przed utworzeniem tagu wydania, aby oznaczony commit zawierał workflow. Zmień APK_ASSET_NAME na dokładną nazwę podpisanego APK dołączanego do każdego wydania.
3. Zbuduj i podpisz APK w istniejącym potoku. Dołącz go do wydania roboczego GitHub jako app-release.apk (lub pod skonfigurowaną nazwą zasobu), a następnie opublikuj wydanie. Przykład obsługuje też prywatne repozytoria przez wbudowany token GitHub z contents: read. APK musi być już dołączony w chwili publikacji wydania; w przeciwnym razie krok pobierania kończy się błędem.

name: Publish APK to Nomid

on:
  release:
    types: [published]

permissions:
  contents: read

concurrency:
  group: nomid-apk-${{ github.event.release.id }}
  cancel-in-progress: false

jobs:
  publish:
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    env:
      APK_ASSET_NAME: app-release.apk
      NOMID_TRACK: ${{ github.event.release.prerelease && 'beta' || 'prod' }}
    steps:
      - name: Set up Python
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
        with:
          python-version: '3.12'

      - name: Download the signed APK from this release
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        shell: bash
        run: |
          set -euo pipefail
          gh release download --repo "$GH_REPO" \
            --pattern "$APK_ASSET_NAME" --output app-release.apk -- "$RELEASE_TAG"
          test -s app-release.apk

      - name: Download and verify the Nomid uploader
        shell: bash
        run: |
          set -euo pipefail
          curl --fail --silent --show-error --output publish_apk.py \
            https://www.nomidmdm.com/developers/publish_apk.py
          printf '%s  %s\n' '8d9ba2a4432e6e6db05ba2411bfb6bfa85c85a79d1ce480d97e0014f965f12d2' publish_apk.py \
            | sha256sum --check --status

      - name: Publish to the Nomid company library
        env:
          NOMID_API_KEY: ${{ secrets.NOMID_API_KEY }}
        shell: bash
        run: |
          set -euo pipefail
          if [[ -z "$NOMID_API_KEY" ]]; then
            echo "Configure the NOMID_API_KEY repository secret before publishing." >&2
            exit 1
          fi
          python3 publish_apk.py app-release.apk --track "$NOMID_TRACK" --timeout 1200

Stabilne wydania są publikowane w prod; wersje wstępne (prerelease) GitHub są publikowane w beta. Dla nowej aplikacji Nomid zawsze uwzględnia prod przy pierwszej publikacji, nawet gdy zażądano beta. Wersja wstępna nowego pakietu nie jest więc odizolowana od prod. Kolejne wydania zachowują jawny wybór ścieżki. Wybierz typ wydania i ścieżkę przed publikacją.

Klucz Nomid jest przekazywany wyłącznie do kroku publikacji przez jego środowisko. Brak klucza, brak APK, niezgodność sumy kontrolnej, nieudana publikacja lub przekroczenie limitu czasu publikacji kończy zadanie błędem. Pomyślne zadanie potwierdza publikację w bibliotece, a nie instalację na urządzeniach. W razie przerwania użyj zapisanego sessionId z tym samym APK i tą samą ścieżką, jak opisano powyżej; ponowne uruchomienie całego workflow rozpoczyna nowe przesyłanie.

Jeśli inny workflow publikuje wydanie GitHub przy użyciu wbudowanego GITHUB_TOKEN, GitHub nie uruchamia tego workflow wydania. W takim przypadku uruchom zweryfikowany skrypt przesyłający bezpośrednio w istniejącym zadaniu wydania po dołączeniu APK albo opublikuj wydanie, używając tokenu aplikacji GitHub lub osobistego tokenu dostępu o odpowiednim zakresie. Trzymaj GH_TOKEN kroku pobierania oddzielnie od klucza API Nomid.

Dokumentacja GitHub: uruchamianie workflow z innego workflow

Błędy i odzyskiwanie

• 401: klucz nie został podany albo jest nieprawidłowy, wygasły lub unieważniony. Sprawdź wstrzykiwanie sekretów w CI bez wypisywania wartości.
• 403: klucz nie ma uprawnienia LIBRARY_MANAGE. Utwórz odpowiednio autoryzowany klucz; niepowiązane uprawnienia do odczytu lub zapisu nie wystarczą.
• 404 dla identyfikatora sesji nieznanego w firmie przypisanej do klucza. Potwierdź identyfikator i klucz powiązany z firmą; nie przełączaj się na inną firmę, aby go szukać.
• 400 dla nieprawidłowych pól żądania, w tym rozmiaru w bajtach lub MIME. Popraw żądanie; nie ponawiaj niezmienionych nieprawidłowych danych.
• 410: sesja przesyłania wygasła. Rozpocznij nowe przesyłanie; wcześniej podpisanych adresów URL części nie można użyć ponownie.
• 409 z /abort oznacza, że przesyłanie jest już przetwarzane lub ukończone. Sprawdź jego status zamiast próbować je anulować.
• 422 z /complete oznacza, że przekazane części nie mogą utworzyć pliku. Porównaj pełną listę części i dokładne wartości ETag z punktem końcowym przesłanych części.
• W razie przejściowego błędu sieci lub S3 podpisz ponownie adres URL wygasłej części i użyj ponownie części przesłanych pomyślnie. Przy niepewnym wyniku /complete najpierw odpytaj tę samą sesję. Nieudane sfinalizowane przesyłanie można ponowić tą samą ścieżką finalizacji, dopóki jego sesja jest ważna.