Samouczek: uaktualnianie potoków usługi Azure Data Factory do potoków sieci szkieletowej przy użyciu programu PowerShell

Potoki usługi Azure Data Factory (ADF) można migrować do usługi Microsoft Fabric przy użyciu modułu Microsoft.FabricPipelineUpgrade programu PowerShell. Ten samouczek zawiera przykład wszystkich kroków, które należy wykonać podczas migracji, z określonymi instrukcjami, zrzutami ekranu i krokami rozwiązywania problemów. Aby uzyskać bardziej ogólny, zwięzły przewodnik, zobacz omówienie.

Jak przygotować się do uaktualnienia
Jak uaktualnić potok usługi ADF do potoku Fabric
Odczytywanie i obsługa alertów

Wymagania wstępne

Aby rozpocząć pracę, upewnij się, że masz następujące wymagania wstępne:

Dzierżawa: Obszar roboczy ADF i Fabric muszą być w tej samej dzierżawie identyfikatora Microsoft Entra.
Fabric: konto najemcy z aktywną subskrypcją Fabric — można utworzyć bezpłatne konto.
Zalecenia dotyczące obszaru roboczego Fabric (opcjonalnie): Zalecamy użycie nowego obszaru roboczego Fabric w tym samym regionie co usługa ADF, aby uzyskać najlepszą wydajność przy aktualizacjach.
Uprawnienia: dostęp do odczytu do obszaru roboczego ADF i elementów, które będziesz migrować, oraz uprawnienia współautora lub wyższego poziomu w obszarze roboczym Fabric, do którego będziesz zapisywać.
Sieć i uwierzytelnianie: upewnij się, że możesz zalogować się zarówno do platformy Azure, jak i Fabric z komputera (interaktywnie lub jako jednostka usługi).

Przygotowanie do uaktualnienia

Przed rozpoczęciem aktualizowania potoków sprawdź, czy środowisko ma wymagane narzędzia i moduły:

PowerShell 7.4.2 (x64) lub nowszy
Moduł FabricPipelineUpgrade

Instalowanie programu PowerShell 7.4.2 (x64) lub nowszego

Na maszynie potrzebujesz programu PowerShell 7.4.2 lub nowszego.

Pobieranie programu PowerShell

Instalowanie i importowanie modułu FabricPipelineUpgrade

Otwórz program PowerShell 7 (x64).
Wybierz menu Start, wyszukaj pozycję PowerShell 7, otwórz menu kontekstowe aplikacji i wybierz pozycję Uruchom jako administrator.
W oknie programu PowerShell z podwyższonym poziomem uprawnień zainstaluj moduł z galerii programu PowerShell:
```
Install-Module Microsoft.FabricPipelineUpgrade -Repository PSGallery -SkipPublisherCheck
```

Zaimportuj moduł do sesji:

Import-Module Microsoft.FabricPipelineUpgrade

Jeśli zostanie wyświetlony błąd zasad podpisywania lub wykonywania, uruchom to polecenie, a następnie zaimportuj ponownie moduł:
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

Weryfikowanie instalacji

Uruchom to polecenie, aby potwierdzić poprawne załadowanie modułu:

Get-Command -Module Microsoft.FabricPipelineUpgrade

Zrzut ekranu przedstawiający dane wyjściowe polecenia modułu.

Pozostaw otwarte okno programu PowerShell; Użyjesz go do uaktualnienia.

Pierwsze uaktualnienie

Utworzymy przykładowy potok i zaktualizujemy go do Fabric jako instrukcję krok po kroku.

Utwórz prosty potok ADF

W narzędziu Azure Data Factory Studio utwórz potok i dodaj działanie czekania. Możesz nadać dowolną nazwę, ale w tym samouczku jest używana pipeline1.

Przygotowywanie środowiska programu PowerShell

W oknie PowerShell zamień wartości w <your subscription ID> i uruchom następujące polecenia w PowerShell, aby się zalogować i ustawić subskrypcję.
```
Add-AzAccount 
Select-AzSubscription -SubscriptionId <your subscription ID>
```

Uruchom to polecenie, aby zapisać bezpieczny token usługi ADF dla sesji:

$adfSecureToken = (Get-AzAccessToken -ResourceUrl "https://management.azure.com/").Token

W oknie programu PowerShell zastąp wartości <your subscription ID>, <your Resource Group Name>, i <your Factory Name>, a następnie uruchom:
```
Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName "pipeline1" -AdfToken $adfSecureToken
```
Wskazówka

W przypadku Data Factory z wieloma potokami można zaimportować wszystkie potoki, pomijając parametr -PipelineName.

To polecenie ładuje pipeline i powiązane artefakty z Azure Data Factory oraz tworzy JSON dla pierwszej "Aktualizacji Postępu".

{
  "state": "Succeeded",
  "alerts": [],
  "result": {
    "importedResources": {
      "type": "AdfSupportFile",
      "adfName": "testdatafactory,
      "pipelines": {
        "pipeline1": {
          "name": "pipeline1",
          "type": "Microsoft.DataFactory/factories/pipelines",
          "properties": {
            "activities": [
              {
                "name": "Wait1",
                "type": "Wait",
                "dependsOn": [],
                "userProperties": [],
                "typeProperties": {
                  "waitTimeInSeconds": 1
                }
              }
            ],
            ],
            "policy": {
              "elapsedTimeMetric": {}
            },
            "annotations": [],
            "lastPublishTime": "2025-09-09T02:46:36Z"
          },
          "etag": "aaaaaaaa-bbbb-cccc-1111-222222222222"
        }
      },
      "datasets": {},
      "linkedServices": {},
      "triggers": {}
    }
  },
  "resolutions": []
}

Co oznaczają te pola

state: pokazuje stan. Jeśli widzisz komunikat "Powodzenie", wszystko jest w porządku.
alerty: wyświetla listę wszelkich problemów lub dodatkowych informacji.
result: pokazuje wynik. Tutaj importedResources zawiera listę artefaktów usługi ADF.
rozdzielczości: Służą do mapowania połączonych usług ADF z połączeniami Fabric (w dalszej części dokumentu).

Konwertowanie potoku usługi ADF na potok sieci szkieletowej

W oknie programu PowerShell, wykonaj polecenie Import-AdfFactory, następnie dodaj | i umieść polecenie ConvertTo-FabricResources na końcu wiersza.

Pełne polecenie powinno wyglądać następująco:

Import-AdfFactory -SubscriptionId <your subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Factory Name> -PipelineName  "pipeline1" -AdfToken $adfSecureToken | ConvertTo-FabricResources

Uruchom polecenie. Powinna zostać wyświetlona odpowiedź podobna do następującej:

{
  "state": "Succeeded",
  "alerts": [],
  "result": {
    "exportableFabricResources": [
      {
        "resourceType": "DataPipeline",
        "resourceName": "pipeline1",
        "resolve": [],
        "export": {
          "name": "pipeline1",
          "properties": {
            "activities": [
              {
                "name": "Wait1",
                "type": "Wait",
                "dependsOn": [],
                "userProperties": [],
                "description": null,
                "typeProperties": {
                  "waitTimeInSeconds": 1
                }
              }
            ]
          },
          "annotations": []
        }
      }
    ]
  },
  "resolutions": []
}

Nadal będzie widoczny standardowy postęp uaktualniania, ale teraz pole wyników zawiera element exportableFabricResources. To jest zgodne z planem; przygotowujesz zasoby Fabric do wyeksportowania.

Później poznasz pole rozdzielczości. Na razie w polu eksportu wyświetlany jest potok Fabric z działaniem Oczekiwanie (Wait).

Jeśli zatrzymasz się tutaj, to polecenie działa jak What-If: pokazuje, jakie elementy powstałyby w wyniku uaktualnienia, i jest dobrym sposobem na zweryfikowanie uaktualnienia przed wprowadzeniem jakichkolwiek zmian.

Zbierz informacje z obszaru roboczego Fabric

Przed wyeksportowaniem potoku Fabric będziesz potrzebować kilku informacji z obszaru roboczego Fabric. Otwórz pusty plik tekstowy, aby skopiować potrzebne wartości później.

Otwórz interfejs użytkownika Microsoft Fabric i przejdź do obszaru roboczego usługi Data Factory.
Znajdź swój identyfikator obszaru roboczego i skopiuj go do pliku tekstowego.
Uruchom to polecenie programu PowerShell, aby pobrać token dostępu do sieci szkieletowej i zapisać go dla sesji:
```
$fabricSecureToken = (Get-AzAccessToken -ResourceUrl "https://analysis.windows.net/powerbi/api").Token
```
Wskazówka

Tokeny dostępu wygasają po około godzinie. W takim przypadku ponownie uruchom polecenie. Dowiesz się, że token wygasł, jeśli polecenie Export-FabricResources zwróci błąd wygaśnięcia tokenu.

Eksportowanie potoku sieci szkieletowej

Połącz wszystkie szczegóły zebrane w tym poleceniu:

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline1" -AdfToken $adfSecureToken | ConvertTo-FabricResources | Export-FabricResources -Region <region> -Workspace <workspaceId> -Token $fabricSecureToken

Teraz skopiuj polecenie z dokumentu tekstowego do okna programu PowerShell i uruchom polecenie .

Powinna zostać wyświetlona odpowiedź podobna do następującej:

{
    "state": "Succeeded",
    "alerts": [],
    "result": {
      "exportedFabricResources": {
        "pipeline1": {
          "type": "DataPipeline",
          "workspaceId": "<your Workspace ID>",
          "id": "<The GUID of your new Pipeline>,
          "displayName": "pipeline1",
          "description": null
        }
      }
    }
  }

Oznacza to, że działało! Sekcja exportedFabricResources zawiera nowy potok danych i jego identyfikator. Teraz otwórz obszar roboczy Fabric w Fabric UX. Odśwież stronę, a na liście zobaczysz pipeline1. Otwórz go i znajdziesz dokładnie to, czego oczekujesz!

Drugie uaktualnienie: Kopiowanie niektórych danych

Drugie uaktualnienie jest podobne do pierwszego, ale wprowadza kilka nowych pojęć:

Zestawy danych i połączoneusługi
Resolutions

Aktualizator Fabryki pipeline'ów obecnie obsługuje ograniczony zbiór zestawów danych, dlatego użyjemy połączeń z usługą Azure Blob Storage i zestawów danych JSON. Przyjrzyjmy się.

W programie ADF Studio utwórz potok, który kopiuje plik JSON z jednego folderu w usłudze Azure Blob Storage do innego. Wywołamy ten potok "pipeline2" i połączenie usługi Azure Blob Storage "BlobStore1", ale ponownie możesz użyć dowolnych nazw.

Uruchom to samo polecenie What-If co wcześniej, aby zaimportować potok i sprawdzić, jaki byłby wynik migracji. Pamiętaj, aby zaktualizować nazwę pipeline'u.

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline2" -AdfToken $adfSecureToken | ConvertTo-FabricResources

W danych wyjściowych potok wygląda podobnie do poprzedniego, ale teraz jest więcej szczegółów, w tym dwa eksportowalneFabricResources:

Jeden dla połączenia
Jeden dla potoku

Oto przykład sekcji Połączenie danych wyjściowych:

{
    "resourceName": "BlobStore1",
    "resourceType": "Connection",
    "resolve": [
    {
        "type": "LinkedServiceToConnectionId",
        "key": "BlobStore1",
        "targetPath": "id",
        "hint": {
        "linkedServiceName": "BlobStore1",
        "connectionType": "AzureBlobStorage",
        "datasource": "...",
        "template": {
            "type": "LinkedServiceToConnectionId",
            "key": "BlobStore1",
            "value": "<Fabric Connection ID>"
        }
        }
    }
    ],
    "export": {
    "id": "00000000-0000-0000-0000-000000000000"
    }
}

Krok rozwiązywania mówi: Find the correct GUID and insert it into the id field of this resource. Na razie identyfikator to wszystkie zera (pusty identyfikator GUID). Ponieważ eksporter nie może go rozwiązać, wskazówka zawiera wskazówki dotyczące sposobu rozwiązywania problemu.

Sekcja Potok zawiera podobne kroki:

"resolve": [
  {
    "type": "AdfResourceNameToFabricResourceId",
    "key": "Connection:BlobStore1",
    "targetPath": "properties.activities[0].typeProperties.source.datasetSettings.externalReferences.connection"
  },
  {
    "type": "AdfResourceNameToFabricResourceId",
    "key": "Connection:BlobStore1",
    "targetPath": "properties.activities[0].typeProperties.sink.datasetSettings.externalReferences.connection"
  }
],

Co robią te kroki?

Te resolve kroki są instrukcjami dotyczącymi mapowania połączonych usług ADF do źródła i ujścia działań przy użyciu odpowiedniego identyfikatora połączenia Fabric.

Dlaczego tak się dzieje?

Uaktualniacz nie może znać identyfikatora zasobu Fabric dla połączenia lub potoku, dopóki te zasoby nie istnieją. W związku z tym zawiera on wskazówkę dotyczącą tworzenia niezbędnych zasobów i wypełniania pliku rozwiązania.

Teraz wyeksportujmy Pipeline Fabric (próba 1)

Jeśli tokeny dostępu wygasły, odśwież je teraz.

Uruchom te same kroki, które były używane w poprzedniej lekcji, ale tym razem dla "pipeline2".

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline2" -AdfToken $adfSecureToken | ConvertTo-FabricResources | Export-FabricResources -Region <region> -Workspace <workspaceId> -Token $fabricSecureToken

To kończy się niepowodzeniem. Tym razem polecenie Import | Convert | Export zwraca wartość podobną do następującej:

{
    "state": "Failed",
    "alerts": [
      {
        "severity": "RequiresUserAction",
        "details": "Please use the hint and template to create/find a new connection and add its ID to your resolutions.",
        "connectionHint": {
          "linkedServiceName": "BlobStore1",
          "connectionType": "AzureBlobStorage",
          "datasource": "...",
          "template": {
            "type": "LinkedServiceToConnectionId",
            "key": "BlobStore1",
            "value": "<Fabric Connection ID>"
          }
        }
      }
    ],
    "resolutions": [],
    "result": {}
  }

(Jeśli przeczytasz koniec ostatniego kroku, możesz rozpoznać connectionHint element.)

Błąd informuje, że musimy "dodać identyfikator połączenia do ustawień rozdzielczości".

Co poszło nie tak?

Aktualizator sieci Fabric nie może tworzyć połączeń Fabric samodzielnie. Musisz pomóc, ręcznie tworząc połączenie Fabric, a następnie informując aktualizatora, kiedy z niego korzystać.

Tworzenie pliku rozdzielczości

Najpierw utwórz plik rozwiązania. Możesz nazwać to jakkolwiek i zapisać to w dowolnym miejscu na swojej maszynie (o ile program PowerShell może uzyskać do tego dostęp), ale w tym samouczku użyto D:\Resolutions.json.
Zainicjuj plik za pomocą:
```
[
]
```
Następnie dodaj brakującą rozdzielczość ze wskazówki, którą dał Ci uaktualniacz. Możesz go znaleźć w sekcji "template" w connectionHint sekcji komunikatu o błędzie.
```
[
    "type": "LinkedServiceToConnectionId",
    "key": "BlobStore1",
    "value": "<Fabric Connection ID>"
]
```
Następnie musimy znaleźć ten plik <Fabric Connection ID>. Aby to zrobić, przejdź do obszaru roboczego Fabric w Fabric UX, wybierz ikonę koła zębatego w prawym górnym rogu, a następnie wybierz pozycję Zarządzaj połączeniami i bramami.
Jeśli połączenie nie istnieje jeszcze w Fabric, utwórz nowe połączenie do tego samego konta Azure Blob Storage używanego przez potok ADF. Możesz nadać mu dowolną nazwę, ale w tym samouczku używana jest nazwa "myblob".
Po utworzeniu połączenia umieść kursor na przycisku wielokropka obok nazwy połączenia, aby wyświetlić menu.
Wybierz pozycję Ustawienia z menu, a następnie skopiuj identyfikator połączenia i wklej go w pliku rozwiązania zamiast <Fabric Connection ID>.

Plik rozdzielczości powinien wyglądać mniej więcej tak (twój value będzie inny):

[
    {
        "type": "LinkedServiceToConnectionId",
        "key": "BlobStore1",
        "value": "dddddddd-9999-0000-1111-eeeeeeeeeeee"
    }
]

Skoro już jesteś przy tym, możesz dodać komentarz do rozwiązania w następujący sposób:

[
   {
      "comment": "Resolve the ADF 'BlobStore1' LinkedService to the Fabric 'myblob' Connection",
      "type": "LinkedServiceToConnectionId",
      "key": "BlobStore1",
      "value": "dddddddd-9999-0000-1111-eeeeeeeeeeee"
   }
]

Polecenie cmdlet Import-FabricResolutions

Możesz zaimportować ten plik ustawień rozdzielczości, aby sprawdzić, co robi.

W PowerShell uruchom:

Import-FabricResolutions -rf "D:\Resolutions.json"

Powinieneś zobaczyć:

{
  "state": "Succeeded",
  "alerts": [],
  "result": {},
  "resolutions": [
    {
      "type": "LinkedServiceToConnectionId",
      "key": "BlobStore1",
      "value": "dddddddd-9999-0000-1111-eeeeeeeeeeee"
    }
  ]
}

Jest to kolejny obiekt postępu uaktualniania, ale teraz pole resolutions jest wypełnione.

Możesz uruchomić Import-FabricResolutions w dowolnym momencie w łańcuchu poleceń przedExport-FabricResources. Rezolucje przejdą do dalszych kroków.

Eksportuj Fabric Pipeline (próba 2)

Teraz, gdy mamy plik rozdzielczości, możemy spróbować wyeksportować ponownie po dodaniu Import-FabricResolutions kroku.

Zaktualizuj polecenie, dodając Import-FabricResolutions między elementami Convert i Export:

Import-AdfFactory -SubscriptionId <your Subscription ID> -ResourceGroupName <your Resource Group Name> -FactoryName <your Data Factory Name> -PipelineName  "pipeline2" -AdfToken $adfSecureToken | ConvertTo-FabricResources | Import-FabricResolutions -ResolutionsFilename "<path to your resolutions file>" | Export-FabricResources -Region <region> -Workspace <workspaceId> -Token $fabricSecureToken

Uruchom polecenie w programie PowerShell.

Tym razem to działa! Ponownie sekcja exportedFabricResources pokazuje nowy potok i jego identyfikator.

Teraz otwórz swój obszar roboczy Fabric w Fabric UX. Odśwież stronę, a na liście zobaczysz pipeline1. Otwórz go i znajdziesz dokładnie to, czego oczekujesz!

Dalsze kroki

Teraz, po pomyślnym uaktualnieniu dwóch potoków, możesz użyć poznanych informacji, aby uaktualnić więcej potoków.

Aby uzyskać więcej informacji na temat typów działań i obsługiwanych zestawów danych, zobacz obsługiwane funkcje.
Aby uzyskać więcej informacji na temat tworzenia pliku rozdzielczości dla różnych rodzajów potoków, zobacz , jak dodać połączenia do pliku rozdzielczości.
Aby uzyskać ogólne instrukcje dotyczące przeprowadzania tej migracji przy użyciu programu PowerShell, zobacz: Migrowanie potoków z usługi Azure Data Factory do sieci szkieletowej przy użyciu programu PowerShell.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-09-22