Internetowy interfejs API usługi Power Automate

Od tej pory wszystkie przepływy będą przechowywane w usłudze Common Data Service i będą korzystać z zaawansowanego internetowego interfejsu API.

W tym temacie omówiono zarządzanie przepływami zawartymi na karcie Rozwiązania w usłudze Power Automate. Obecnie przepływy w obszarze Moje przepływy nie są obsługiwane przez te interfejsy API.

Tworzenie żądań HTTP

Aby rozpocząć tworzenie żądań, należy najpierw skonstruować adres URL. Format podstawowego adresu URL internetowego interfejsu API usługi Power Automate to: https://{Organization ID}.{Regional Subdomain}.dynamics.com/api/data/v9.1/. Dwa parametry to:

  • Identyfikator organizacji to unikatowa nazwa środowiska, które przechowuje Twoje przepływy.

  • Poddomena regionalna zależy od lokalizacji środowiska.

Aby uzyskać te dwa parametry.

  1. Przejdź do centrum administracyjnego usługi Power Platform.
  2. Wybierz środowisko, które będzie używane do tworzenia przepływów.

Adres URL przepływu

  1. Skopiuj identyfikator organizacji i poddomenę regionu z adresu URL środowiska.

Adres URL przepływu

Można też programowo pobrać listę dostępnych wystąpień przy użyciu metody Pobierz wystąpienia w interfejsie API zarządzania online.

Każde żądanie do internetowego interfejsu API musi mieć ustawione nagłówki Accept i Content-type na wartość application/json.

Na koniec wypełnij nagłówek Authorization tokenem elementu nośnego usługi Azure AD. Użytkownik może dowiedzieć się, jak uzyskać token okaziciela Azure AD dla programu Common Data Service. Na przykład to żądanie:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...

Odpowiedź zawiera listę przepływów w obrębie tego środowiska:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#workflows",
    "value": [{
        "@odata.etag": "W/\"12116760\"",
        "category": 5,
        "statecode": 0,
        "workflowidunique": "00000000-0000-0000-0000-000000000001",
        "workflowid" : "00000000-0000-0000-0000-000000000002",
        "createdon": "2018-11-15T19:45:51Z",
        "_ownerid_value": "00000000-0000-0000-0000-000000000003",
        "modifiedon": "2018-11-15T19:45:51Z",
        "ismanaged": false,
        "name": "Sample flow",
        "_modifiedby_value": "00000000-0000-0000-0000-000000000003",
        "_createdby_value": "00000000-0000-0000-0000-000000000003",
        "type": 1,
        "description": "This flow updates some data in Common Data Service.",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"source\":\"NotSpecified\",\"id\":\"/providers/Microsoft.PowerApps/apis/shared_commondataservice\",\"tier\":\"NotSpecified\"}},\"definition\":{...}},\"schemaVersion\":\"1.0.0.0\"}"
    }]
}

Lista przepływów

Jak pokazano powyżej, możesz pobrać listę przepływów pracy, wywołując GET w workflows. Każdy przepływ pracy ma wiele właściwości, ale najistotniejsze to:

Nazwa właściwości Opis
category Kategoria przepływu. Różne typy to: 0 — klasyczne przepływy pracy usługi Common Data Service, 1 — klasyczne okna dialogowe usługi Common Data Service, 2 — reguły biznesowe, 3 — klasyczne akcje usługi Common Data Service, 4 — przepływy procesów biznesowych i 5 — zautomatyzowane, natychmiastowe lub zaplanowane przepływy.
statecode Stan przepływu. Możliwe stany to 0 — wyłączony lub 1 — włączony.
workflowuniqueid Unikatowy identyfikator dla tej instalacji przepływu.
workflowid Unikatowy identyfikator dla przepływu w chmurze we wszystkich importach.
createdon Data utworzenia przepływu.
_ownerid_value Unikatowy identyfikator użytkownika lub zespołu będącego właścicielem przepływu. Jest to identyfikator z jednostki systemusers w usłudze Common Data Service.
modifiedon Czas ostatniej aktualizacji przepływu.
ismanaged Wskazuje, czy przepływ został zainstalowany przy użyciu rozwiązania zarządzanego.
nazwa Nazwa wyświetlana nadana przepływowi przez Ciebie.
_modifiedby_value Ostatni użytkownik, który zaktualizował przepływ. Jest to identyfikator z jednostki systemusers w usłudze Common Data Service.
_createdby_value Użytkownik, który utworzył przepływ. Jest to identyfikator z jednostki systemusers w usłudze Common Data Service.
typ Wskazuje, czy przepływ to uruchomiony przepływ, czy szablon, którego można użyć do tworzenia dodatkowych przepływów. 1 — przepływ, 2 — aktywacja lub 3 — szablon.
opis Podany przez użytkownika opis przepływu.
clientdata Zakodowany w ciągu JSON obiektu, który zawiera odwołania połączenia i definicję przepływu.

Możesz również zażądać konkretnych właściwości, przefiltrować listę przepływów i nie tylko, jak opisano w dokumentacji interfejsu API usługi Common Data Service dotyczącej wykonywania zapytań na danych. Na przykład to zapytanie zwraca tylko zautomatyzowane, natychmiastowe lub zaplanowane przepływy, które są obecnie włączone:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows?$filter=category eq 5 and statecode eq 1
Accept: application/json
Authorization: Bearer ey...

Tworzenie przepływu w chmurze

Wywołaj metodę POST w kolekcji workflows, aby utworzyć przepływ w chmurze. Wymagane właściwości zautomatyzowanych, natychmiastowych i zaplanowanych przepływów to: kategoria, nazwa, typ, encja podstawowa i dane klienta. Użyj none dla właściwości primaryentity w przypadku tych typów przepływów.

Możesz również podać właściwości description (opis) i statecode (kod stanu).

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
        "category": 5,
        "statecode": 0,
        "name": "Sample flow name",
        "type": 1,
        "description": "This flow reads some data from Common Data Service.",
        "primaryentity":"none",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"connectionName\":\"shared-commondataser-00000000-0000-0000-0000-000000000004\",\"source\":\"Invoker\",\"id\":\"/providers/Microsoft.Power Apps/apis/shared_commondataservice\"}},\"definition\":{\"$schema\": \"https:\/\/schema.management.azure.com\/providers\/Microsoft.Logic\/schemas\/2016-06-01\/workflowdefinition.json#\",\"contentVersion\": \"1.0.0.0\",\"parameters\": {\"$connections\": {\"defaultValue\": {},\"type\": \"Object\"},\"$authentication\": {\"defaultValue\": {},\"type\": \"SecureObject\"}},\"triggers\": {\"Recurrence\": {\"recurrence\": {\"frequency\": \"Minute\",\"interval\": 1},\"type\": \"Recurrence\"}},\"actions\": {\"List_records\": {\"runAfter\": {},\"metadata\": {\"flowSystemMetadata\": {\"swaggerOperationId\": \"GetItems_V2\"}},\"type\": \"ApiConnection\",\"inputs\": {\"host\": {\"api\": {\"runtimeUrl\": \"https:\/\/firstrelease-001.azure-apim.net\/apim\/commondataservice\"},\"connection\": {\"name\": \"@parameters('$connections')['shared_commondataservice']['connectionId']\"}},\"method\": \"get\",\"path\": \"\/v2\/datasets\/@{encodeURIComponent(encodeURIComponent('default.cds'))}\/tables\/@{encodeURIComponent(encodeURIComponent('accounts'))}\/items\",\"queries\": {\"$top\": 1},\"authentication\": \"@parameters('$authentication')\"}}},\"outputs\": {}}},\"schemaVersion\":\"1.0.0.0\"}"
}

Najważniejsza sekcja to clientdata, która zawiera odwołania przepływu używane przez przepływ, oraz definicję przepływu. Odwołania przepływu to mapowania do każdego połączenia używanego w przepływie.

Dostępne są trzy właściwości:

Nazwa właściwości Opis
connectionName Określa połączenie. Właściwość connectionName można wyświetlić, przechodząc do strony Połączenia, a następnie kopiując ją z adresu URL połączenia.
źródło Embedded lub Invoker. Invoker obowiązuje tylko w przypadku przepływów natychmiastowych (tych, w których użytkownik wybiera przycisk, aby uruchomić przepływ) oraz wskazuje, że użytkownik końcowy udostępni połączenie. W tym przypadku właściwość connectionName jest używana tylko w czasie projektowania. Jeśli połączenie ma Embedded, oznacza to, że jest zawsze używana określona przez Ciebie właściwość connectionName.
identyfikator Identyfikator łącznika. Identyfikator zawsze zaczyna się od /providers/Microsoft.PowerApps/apis/, a następnie zawiera nazwę łącznika, którą można skopiować z adresu URL połączenia lub wybierając łącznik ze strony Łączniki.

Po wykonaniu żądania POST otrzymasz nagłówek OData-EntityId, który będzie zawierać workflowid dla nowego przepływu.

Aktualizacja przepływu w chmurze

Możesz wywołać metodę PATCH w przepływie pracy, aby zaktualizować, włączyć lub wyłączyć przepływ w chmurze. Użyj workflowid do nawiązywania tych wywołań. Na przykład możesz zaktualizować opis i właściciela przepływu przy użyciu następującego wywołania:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "description" : "This flow will ensure consistency across systems.",
    "ownerid@odata.bind": "systemusers(00000000-0000-0000-0000-000000000005)",
}

Uwaga

W składni zmieniania właściciela jest używany format odata.bind. Oznacza to, że zamiast stosowania poprawek _pola ownerid_value bezpośrednio, możesz dołączyć @odata.bind do nazwy właściwości, a następnie opakować identyfikator za pomocą systemusers().

W kolejnym przykładzie można włączyć przepływ w chmurze przy użyciu tego wywołania:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "statecode" : 1
}

Usuwanie przepływ w chmurze

Usuń przepływ w chmurze przy użyciu prostego wywołania DELETE:

DELETE https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...

Uwaga

Nie można usunąć przepływu w chmurze, który jest włączony. Należy najpierw wyłączyć przepływ (zobacz Aktualizowanie przepływu w chmurze wcześniej) lub w przeciwnym razie zostanie wyświetlony następujący błąd: Cannot delete an active workflow definition.

Uzyskiwanie listy wszystkich użytkowników, którym udostępniono przepływ w chmurze

Do pobierania listy użytkowników mających dostęp jest używana funkcja w usłudze Common Data Service. Ta funkcja przyjmuje pojedynczy parametr Target:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/RetrieveSharedPrincipalsAndAccess(Target=@tid)?@tid={'@odata.id':'workflows(00000000-0000-0000-0000-000000000002)'}
Accept: application/json
Authorization: Bearer ey...

Parametr Target to ciąg w formacie JSON z pojedynczą właściwością o nazwie @odata.id. Zastąp identyfikator przepływu pracy w powyższym przykładzie. Zostanie zwrócona następująca wartość:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveSharedPrincipalsAndAccessResponse",
    "PrincipalAccesses": [
        {
            "AccessMask": "ReadAccess",
            "Principal": {
                "@odata.type": "#Microsoft.Dynamics.CRM.systemuser",
                "ownerid": "00000000-0000-0000-0000-000000000005"
            }
        }
    ]
}

Udostępnianie lub anulowanie udostępniania przepływu w chmurze

Możesz udostępnić przepływ w chmurze używając akcji GrantAccess.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/GrantAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "PrincipalAccess": {
        "Principal": {
            "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
            "ownerid" : "00000000-0000-0000-0000-000000000005"
        },
        "AccessMask": "ReadAccess"
    }
}

Parametr AccessMask to pole z następującymi wartościami dla różnych poziomów uprawnień:

Nazwisko Opis
Brak Brak dostępu.
Dostęp do odczytu Uprawnienie do odczytywania przepływu.
WriteAccess Uprawnienie do aktualizowania przepływu.
DeleteAccess Uprawnienie do usuwania przepływu.
ShareAccess Uprawnienie do udostępniania przepływu.
AssignAccess Uprawnienie do zmieniania właściciela przepływu.

Uprawnienia możesz połączyć przy użyciu przecinka, na przykład zapewniając możliwość odczytywania i aktualizowania przepływu w chmurze, podając wartość ReadAccess,WriteAccess.

Możesz anulować udostępnianie przepływu w chmurze przy użyciu akcji RevokeAccess. Oto przykład:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/RevokeAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "Revokee": {
        "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
        "ownerid" : "00000000-0000-0000-0000-000000000005"
    }
}

Akcja RevokeAccess usuwa wszystkie uprawnienia udzielone w akcji AccessMask.

Eksportowanie przepływów

Użyj akcji ExportSolution, aby wyeksportować przepływy do pliku zip. Najpierw dodaj odpowiednie przepływy do rozwiązania.

Gdy przepływ będzie w rozwiązaniu, wywołaj następującą akcję:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ExportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "SolutionName" : "Awesome solution 1",
    "Managed": false
}

Akcja ExportSolution zwraca ciąg zakodowany algorytmem base-64 we właściwości ExportSoutionFile.

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ExportSolutionResponse",
    "ExportSolutionFile": "UEsDBBQAAgAI..."
}

Następnie możesz zapisać ten plik w kontroli kodu źródłowego i/lub używać dowolnego systemu dystrybucji lub zarządzania wersjami.

Importowanie przepływów

Wywołaj akcję ImportSolution, aby zaimportować rozwiązanie.

Nazwa właściwości Opis
OverwriteUnmanagedCustomizations Jeśli istnieją wystąpienia tych przepływów w usłudze Common Data Service, tę flagę należy ustawić na wartość true, aby je zaimportować. W przeciwnym razie nie zostaną one zastąpione.
PublishWorkflows Wskazuje, czy klasyczne przepływy pracy usługi Common Data Service zostaną aktywowane przy importowaniu. To ustawienie nie ma zastosowania do innych typów przepływów.
ImportJobId Oferuje nowy, unikatowy identyfikator GUID do śledzenia zadania importu.
CustomizationFile Plik zip zakodowany algorytmem base-64, który zawiera rozwiązanie.
POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ImportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "OverwriteUnmanagedCustomizations": false,
    "PublishWorkflows" : true,
    "ImportJobId" : "00000000-0000-0000-0000-000000000006",
    "CustomizationFile" : "UEsDBBQAAgAI..."
}

Ponieważ importowanie to długotrwała operacja, odpowiedzią na akcję ImportSolution będzie wartość 204 No content. Aby śledzić postęp, wywołaj GET na obiekcie importjobs pod warunkiem, że wartość ImportJobId została uwzględniona w oryginalnej akcji ImportSolution.

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/importjobs(00000000-0000-0000-0000-000000000006)
Accept: application/json
Authorization: Bearer ey...

To wywołanie zwróci stan operacji importowania, w tym progress (procent ukończenia), startedon i completedon (jeśli importowanie zostało zakończone).

Po pomyślnym zakończeniu importowania musisz skonfigurować połączenia dla przepływu, ponieważ connectionNames będzie prawdopodobnie inna w środowisku docelowym (jeśli w ogóle istnieją połączenia). Jeśli konfigurujesz nowe połączenia w środowisku docelowym, właściciel przepływów musi utworzyć je w projektancie usługi Power Automate. Jeśli połączenia są już skonfigurowane w nowym środowisku, możesz wywołać PATCH dla clientData przepływu, używając nazw połączeń.