Samouczek: automatyzowanie usługi Azure Device Provisioning Przy użyciu funkcji GitHub Actions

Użyj narzędzi automatyzacji, takich jak GitHub Actions, aby zarządzać cyklem życia urządzenia IoT. W tym samouczku przedstawiono przepływ pracy funkcji GitHub Actions, który łączy urządzenie z centrum IoT Hub przy użyciu usługi Azure Device Provisioning Service (DPS).

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

• Zapisz poświadczenia uwierzytelniania jako wpisy tajne repozytorium.
• Utwórz przepływ pracy, aby aprowizować zasoby usługi IoT Hub i Device Provisioning Service.
• Uruchom przepływ pracy i monitoruj symulowane urządzenie podczas nawiązywania połączenia z usługą IoT Hub.

Wymagania wstępne

• Subskrypcja platformy Azure

  Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

• Interfejs wiersza polecenia platformy Azure

  • Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell.

  • Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze platformy Docker.

    • Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login.

    • Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.

• Konto usługi GitHub z repozytorium, którego jesteś właścicielem, lub repozytorium, do którego masz dostęp administratora. Aby uzyskać więcej informacji, zobacz Wprowadzenie do usługi GitHub.

1 — Tworzenie wpisów tajnych repozytorium

Przepływ pracy zdefiniowany w następnej sekcji wymaga dostępu do subskrypcji platformy Azure w celu tworzenia zasobów i zarządzania nimi. Nie chcesz umieszczać tych informacji w niechronionym pliku, w którym można go odnaleźć, więc zamiast tego użyjemy wpisów tajnych repozytorium do przechowywania tych informacji, ale nadal udostępniamy je jako zmienną środowiskową w przepływie pracy. Aby uzyskać więcej informacji, zobacz Zaszyfrowane wpisy tajne.

Tylko właściciele repozytoriów i administratorzy mogą zarządzać wpisami tajnymi repozytorium.

Tworzenie jednostki usługi

Zamiast podawać poświadczenia dostępu osobistego, utworzymy jednostkę usługi, a następnie dodamy te poświadczenia jako wpisy tajne repozytorium. Użyj interfejsu wiersza polecenia platformy Azure, aby utworzyć nową jednostkę usługi. Aby uzyskać więcej informacji, zobacz Tworzenie jednostki usługi platformy Azure.

1. Użyj polecenia az ad sp create-for-rbac, aby utworzyć jednostkę usługi z dostępem współautora do określonej grupy zasobów. Zastąp <SUBSCRIPTION_ID> wartości i <RESOURCE_GROUP_NAME> własnymi informacjami.

   To polecenie wymaga ról administratora dostępu właściciela lub użytkownika w subskrypcji.

   az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
   

2. Skopiuj następujące elementy z danych wyjściowych polecenia tworzenia jednostki usługi, aby użyć go w następnej sekcji:

   • ClientId.
   • ClientSecret. Jest to wygenerowane hasło dla jednostki usługi, do której nie będzie można uzyskać dostępu ponownie.
   • TenantId.

3. Użyj polecenia az role assignment create, aby przypisać dwie kolejne role dostępu do jednostki usługi: Współautor danych usługi Device Provisioning Service i Współautor danych usługi IoT Hub. Zastąp <SP_CLIENT_ID> ciąg wartością clientId skopiowaną z danych wyjściowych poprzedniego polecenia.

   az role assignment create --assignee "<SP_CLIENT_ID>" --role "Device Provisioning Service Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
   

   az role assignment create --assignee "<SP_CLIENT_ID>" --role "IoT Hub Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
   

Zapisywanie poświadczeń jednostki usługi jako wpisów tajnych

1. W GitHub.com przejdź do Ustawienia dla repozytorium.

2. Wybierz pozycję Wpisy tajne z menu nawigacji, a następnie wybierz pozycję Akcje.

3. Wybierz pozycję Nowy wpis tajny repozytorium.

4. Utwórz wpis tajny dla identyfikatora jednostki usługi.

   • Nazwa: APP_ID
   • Wpis tajny: wklej identyfikator clientId skopiowany z danych wyjściowych polecenia tworzenia jednostki usługi.

5. Wybierz pozycję Dodaj wpis tajny, a następnie wybierz pozycję Nowy wpis tajny repozytorium, aby dodać drugi wpis tajny.

6. Utwórz wpis tajny dla hasła jednostki usługi.

   • Nazwa: SECRET
   • Wpis tajny: wklej element clientSecret skopiowany z danych wyjściowych polecenia tworzenia jednostki usługi.

7. Wybierz pozycję Dodaj wpis tajny, a następnie wybierz pozycję Nowy wpis tajny repozytorium, aby dodać ostateczny wpis tajny.

8. Utwórz wpis tajny dla dzierżawy platformy Azure.

   • Nazwa: TENANT
   • Wpis tajny: wklej identyfikator tenantId skopiowany z danych wyjściowych polecenia tworzenia jednostki usługi.

9. Wybierz przycisk Add secret (Dodaj wpis tajny).

2 — Tworzenie przepływu pracy

Przepływ pracy funkcji GitHub Actions definiuje zadania, które będą uruchamiane po wyzwoleniu go przez zdarzenie. Przepływ pracy zawiera jedno lub więcej zadań , które mogą być uruchamiane równolegle lub sekwencyjnie. Aby uzyskać więcej informacji, zobacz Omówienie funkcji GitHub Actions.

Na potrzeby tego samouczka utworzymy jeden przepływ pracy zawierający zadania dla każdego z następujących zadań:

• Aprowizuj wystąpienie usługi IoT Hub i wystąpienie usługi DPS.
• Połącz wystąpienia usługi IoT Hub i DPS ze sobą.
• Utwórz rejestrację indywidualną w wystąpieniu usługi DPS i zarejestruj urządzenie w centrum IoT Przy użyciu uwierzytelniania klucza symetrycznego za pośrednictwem rejestracji usługi DPS.
• Symulowanie urządzenia przez pięć minut i monitorowanie zdarzeń centrum IoT Hub.

Przepływy pracy to pliki YAML znajdujące się w .github/workflows/ katalogu repozytorium.

1. W repozytorium GitHub przejdź do karty Akcje .

2. W okienku Akcje wybierz pozycję Nowy przepływ pracy.

3. Na stronie Wybieranie przepływu pracy możesz wybrać wstępnie utworzone szablony do użycia. Na potrzeby tego samouczka utworzymy własny przepływ pracy, więc wybierz pozycję Skonfiguruj przepływ pracy samodzielnie.

4. Usługa GitHub tworzy nowy plik przepływu pracy. Zwróć uwagę, że znajduje się on w .github/workflows/ katalogu . Nadaj nowemu plikowi zrozumiałą nazwę, na przykład dps-tutorial.yml.

5. Dodaj parametr name, aby nadać przepływowi pracy nazwę.

   name: DPS Tutorial
   

6. Dodaj parametr on.workflow_dispatch. Parametr on określa, kiedy zostanie uruchomiony przepływ pracy. Parametr workflow_dispatch wskazuje, że chcemy ręcznie wyzwolić przepływ pracy. Za pomocą tego parametru możemy zdefiniować inputs , że zostanie przekazany do przepływu pracy w każdym uruchomieniu, ale nie będziemy używać tych w tym samouczku.

   on: workflow_dispatch
   

7. Zdefiniuj zmienne środowiskowe dla zasobów tworzonych w przepływie pracy. Te zmienne będą dostępne dla wszystkich zadań w przepływie pracy. Można również zdefiniować zmienne środowiskowe dla poszczególnych zadań lub poszczególnych kroków w ramach zadań.

   Zastąp wartości symboli zastępczych własnymi wartościami. Upewnij się, że określono tę samą grupę zasobów, do której jednostka usługi ma dostęp.

   env:
     HUB_NAME: <Globally unique IoT hub name>
     DPS_NAME: <Desired Device Provisioning Service name>
     DEVICE_NAME: <Desired device name>
     RESOURCE_GROUP: <Solution resource group where resources will be created>
   

8. Zdefiniuj zmienne środowiskowe dla wpisów tajnych utworzonych w poprzedniej sekcji.

     SP_USER: ${{ secrets.APP_ID }}
     SP_SECRET: ${{ secrets.SECRET }}
     SP_TENANT: ${{ secrets.TENANT }}
   

9. Dodaj parametr zadania do pliku przepływu pracy.

   jobs:
   

10. Zdefiniuj pierwsze zadanie dla naszego przepływu pracy, które wywołamy provision . To zadanie aprowizuje wystąpienia usługi IoT Hub i DPS:

      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
    

    Aby uzyskać więcej informacji na temat poleceń uruchamianych w tym zadaniu, zobacz:

    • az iot hub create
    • az iot dps create

11. Zdefiniuj zadanie configure dla wystąpień usług DPS i IoT Hub. Zwróć uwagę, że to zadanie używa parametru needs , co oznacza, że configure zadanie nie zostanie uruchomione, dopóki zadanie nie zakończy własnego uruchomienia.

      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"   
    

    Aby uzyskać więcej informacji na temat poleceń uruchamianych w tym zadaniu, zobacz:

    • az iot dps linked-hub create

12. Zdefiniuj zadanie o nazwie register , które spowoduje utworzenie rejestracji indywidualnej, a następnie użycie tej rejestracji w celu zarejestrowania urządzenia w usłudze IoT Hub.

      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login   
    

    Uwaga

    To zadanie i inne używają parametru --auth-type login w niektórych poleceniach, aby wskazać, że operacja powinna używać jednostki usługi z bieżącej sesji firmy Microsoft Entra. Alternatywa --auth-type key nie wymaga konfiguracji jednostki usługi, ale jest mniej bezpieczna.

    Aby uzyskać więcej informacji na temat poleceń uruchamianych w tym zadaniu, zobacz:

    • az iot dps enrollment create
    • az iot device registration create

13. Zdefiniuj zadanie dla simulate urządzenia IoT, które będzie łączyć się z centrum IoT Hub i wysyłać przykładowe komunikaty telemetryczne.

      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
    

    Aby uzyskać więcej informacji na temat poleceń uruchamianych w tym zadaniu, zobacz:

    • az iot device simulate

14. Zdefiniuj zadanie punktu monitor końcowego centrum IoT dla zdarzeń i obserwuj komunikaty pochodzące z symulowanego urządzenia. Zwróć uwagę, że zadania symulowania i monitorowania definiują zadanie rejestrowania w parametrze needs . Ta konfiguracja oznacza, że po pomyślnym zakończeniu zadania rejestracji oba te zadania będą uruchamiane równolegle.

      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y   
    

    Aby uzyskać więcej informacji na temat poleceń uruchamianych w tym zadaniu, zobacz:

    • az iot hub monitor-events

15. Pełny plik przepływu pracy powinien wyglądać podobnie do tego przykładu, a informacje zastępują wartości symboli zastępczych w zmiennych środowiskowych:

    name: DPS Tutorial
    
    on: workflow_dispatch
    
    env:
      HUB_NAME: <Globally unique IoT hub name>
      DPS_NAME: <Desired Device Provisioning Service name>
      DEVICE_NAME: <Desired device name>
      RESOURCE_GROUP: <Solution resource group where resources will be created>
      SP_USER: ${{ secrets.APP_ID }}
      SP_SECRET: ${{ secrets.SECRET }}
      SP_TENANT: ${{ secrets.TENANT }}
    
    jobs:
      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"
      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login
      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y
    

16. Zapisz, zatwierdź i wypchnij ten nowy plik do repozytorium GitHub.

3 — Uruchamianie przepływu pracy

1. Przejdź do karty Akcje repozytorium GitHub.

2. W okienku Akcje wybierz pozycję Samouczek usługi DPS, czyli nazwę zdefiniowaną w pliku przepływu pracy, a następnie wybierz pole rozwijane Uruchom przepływ pracy.

   

3. Zmień gałąź, jeśli przepływ pracy został utworzony w gałęzi innej niż główna, a następnie wybierz pozycję Uruchom przepływ pracy.

4. Zostanie wyświetlone nowe uruchomienie przepływu pracy. Wybierz nazwę, aby wyświetlić szczegóły przebiegu.

5. W podsumowaniu przepływu pracy można obserwować, jak każde zadanie rozpoczyna się i kończy. Wybierz dowolną nazwę zadania, aby wyświetlić jego szczegóły. Symulowane zadanie urządzenia jest uruchamiane przez pięć minut i wysyła dane telemetryczne do usługi IoT Hub. W tym czasie wybierz zadanie symulowania , aby obserwować wysyłanie komunikatów z urządzenia, a zadanie monitorowania , aby obserwować odbieranie tych komunikatów przez usługę IoT Hub.

6. Po pomyślnym zakończeniu wszystkich zadań powinny zostać wyświetlone zielone znaczniki wyboru według każdego z nich.

   

Czyszczenie zasobów

Jeśli nie zamierzasz nadal korzystać z tych zasobów utworzonych w tym samouczku, usuń je, wykonując następujące kroki.

Użyj interfejsu wiersza polecenia platformy Azure:

1. Wyświetl listę zasobów w grupie zasobów.

   az resource list --resource-group <RESOURCE_GROUP_NAME>
   

2. Aby usunąć poszczególne zasoby, użyj identyfikatora zasobu.

   az resource delete --resource-group <RESOURCE_GROUP_NAME> --ids <RESOURCE_ID>
   

3. Jeśli chcesz usunąć całą grupę zasobów i wszystkie zasoby w niej, uruchom następujące polecenie:

   az group delete --resource-group <RESOURCE_GROUP_NAME>
   

Korzystanie z witryny Azure Portal:

1. W witrynie Azure Portal przejdź do grupy zasobów, w której utworzono nowe zasoby.
2. Możesz usunąć całą grupę zasobów lub wybrać poszczególne zasoby, które chcesz usunąć, a następnie wybrać pozycję Usuń.

Następne kroki

Dowiedz się, jak aprowizować wystąpienia usługi DPS przy użyciu innych narzędzi automatyzacji.

Konfigurowanie usługi DPS przy użyciu Bicep