Kod kullanarak masaüstü akışları ile çalışma

Geliştiriciler, masaüstü akışlarını program aracılığıyla tetikleme ve iptal etme dahil uygulamalarına masaüstü akışları işlevselliği ekleyebilirler. Bu özellikler, Microsoft Dataverse platformunun bir parçası olarak sunulur.

Önkoşullar

1. Dataverse Web API, Dataverse ile kimlik doğrulaması ve Dataverse ile OAuth kullanma bilgisi.
2. Dataverse ortam ve kuruluş kavramları ve manuel olarak veya program aracılığıyla kuruluş URL'sini alma hakkında bilgi.
3. Masaüstü akışı kavramları ve bağlantılar ve bağlantıların nasıl oluşturulacağı hakkında bilgi.

Kullanılabilir masaüstü akışlarını listeleme

Tüm masaüstü akışı betikleri Dataverse'te iş akışı varlığının bölümü olarak bulunur.

Masaüstü akışlarını tanımlamak için iş akışları listesini kategoriye göre filtreleyin.

Masaüstü akışları alma isteği

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1  

Masaüstü akışlarını alma isteğine yanıt

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#workflows(name,workflowid)",
    "value": [
        {
            "@odata.etag": "W1069462",
            "name": "Desktop flow 1",
            "workflowid": "f091ffab-58bb-4630-a115-659453d56f59",
        },
        {
            "@odata.etag": "W1028555",
            "name": "Desktop flow 2",
            "workflowid": "eafba1a2-e8d4-4efa-b549-11d4dfd9a3d1",
        }
    ]
}

Masaüstü akışları için şemayı alma

Girişler ve/veya çıkışlar için akış şemasını almanız gerekiyorsa hedef iş akışı için clientData alanını kullanabilirsiniz.

Masaüstü akışları için şemayı isteme

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/clientdata/$value HTTP/1.1  

Masaüstü akışları şemasını alma isteğine yanıt

{
    "clientversion": "2.19.00170.22097",
    "properties": {
        "definition": {
            "dependencies": [],
            "isvalid": true,
            "name": "Desktop Flow 1",
            "package": "UEsDBBQAAAAIAIqZlF...",
            "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#"
        },
        "inputs": {
            "schema": {
                "properties": {
                    "Input1": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Input 1",
                        "type": "string",
                        "value": "0"
                    },
                    "Input2": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Input2",
                        "type": "string",
                        "value": ""
                    }
                },
                "type": "object"
            }
        },
        "outputs": {
            "schema": {
                "properties": {
                    "Output1": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Output",
                        "type": "string",
                        "value": null
                    }
                },
                "type": "object"
            }
        }
    },
    "schemaversion": "ROBIN_20211012",
    "targets": {
        "schema": {
            "properties": {},
            "type": "object"
        }
    }
}

Masaüstü akış çalıştırmasının durumunu alma

Dataverse, tüm masaüstü akışı çalıştırmalarını akış oturumu varlığında depolar.

Masaüstü akış çalıştırmasının durumunu isteme

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])?$select=statuscode,statecode,startedon,completedon HTTP/1.1  

Masaüstü akış çalıştırmasının durumu için yanıt

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#flowsessions(statuscode,statecode,startedon,completedon)/$entity",
    "@odata.etag": "W1276122",
    "statuscode": 8,
    "statecode": 0,
    "startedon": "2022-06-16T12:54:40Z",
    "completedon": "2022-06-16T12:57:46Z",
}

Masaüstü akışı çıkışlarını alma

Masaüstü akışında çıkışlar varsa bunları almak için çıkışlar alanını sorgulayabilirsiniz.

Masaüstü akışı çıkışlarını isteme

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1  

Masaüstü akışı çıkışları isteği için yanıt

{
    "Output1": "My output value"
}

Masaüstü akış çalıştırması tetikleme

Dataverse kullanarak, uygulamanız aracılığıyla bir masaüstü akışı tetikleme işlevi ekleyebilirsiniz. Bu işlevi uygulamak için RunDesktopFlow eylemini kullanmanız gerekir.

Eylemi çağırmak için aşağıdaki bilgiler gereklidir.

• Çalıştırmak istediğiniz masaüstü akışına ait ID. Bu kimliği API aracılığıyla bu makalenin önceki kısmında bulunan Kullanılabilir masaüstü akışlarını listele bölümünde açıklandığı şekilde alabilirsiniz.

  Tip

  Alternatif olarak, kimliği Power Automate'te manuel olarak masaüstü akışı ayrıntıları URL'sinden alabilirsiniz. URL biçimi: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

  Daha fazla bilgi için bkz. Masaüstü akışlarını yönetme.

• Akışınızı çalıştırmak için kullanılacak masaüstü akış bağlantısı name (hedef makine/makine grubu). Bu ad, Power Automate'te aynı bağlantı sayfasının URL'sinden alınabilir. URL biçimi:
  https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

  Note

  Daha fazla bilgi için bkz. Masaüstü akış bağlantıları oluşturma.

  Tip

  Alternatif olarak, bağlantının giriş olarak bağlantı adı yerine bağlantı başvurusunun mantıksal adını kullanabilirsiniz (aşağıda açıklana kullanım örneği). Bağlantı başvuruları Dataverse tablosu bağlantı başvurusunda depolanır ve Kullanılabilir masaüstü akışlarını listele bölümünde ayrıntılandığı şekilde masaüstü akışlarla aynı şekilde programlı olarak listelenebilir.

  Daha fazla bilgi için bkz. Bir çözümde bağlantı başvurusu kullanma ve bağlantı başvurusu tablosu/varlık başvurusu.

Masaüstü akışını tetikleme isteği

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Name]",
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

Bir bağlantı başvurusuyla masaüstü akışını tetikleme isteği

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Reference Logical Name]",
    "connectionType": 2,
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

Masaüstü akışını tetikleme isteğinden gelen yanıt

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
    "flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}

Betik tamamlandığında bildirim alma

İsteğe bağlı bir parametre "callbackUrl" RunDesktopFlow eyleminin gövdesinde mevcuttur. Betiğinizin tamamlandığına dair bildirim almak istiyorsanız bunu kullanabilirsiniz. Betik tamamlandığında sağlanan URL'ye bir POST isteği gönderilir.

Geri arama uç noktası tarafından alınan istek

User-Agent: EnterpriseConnectors/1.0
Content-type: application/json; charset=utf-8
x-ms-workflow-id: [Workflow ID]
x-ms-run-id: [Flow session ID]

POST [yourCallbackURL]  

{
    "statuscode": 4,
    "statecode": 0,
    "startedon": "2022-09-05T08:04:11Z",
    "completedon": "2022-09-05T08:04:41Z",
    "flowsessionid": "d9687093-d0c0-ec11-983e-0022480b428a"
}

Geri arama URL parametresi sağlanmışsa akış oturumu durumu Dataverse'den sorgulanmalıdır (bkz. Masaüstü akış çalıştırmasının durumunu alma).

Geri arama URL parametresi gereksinimleri

• Sunucunuz geçerli TLS ve şifre paketleri olmalıdır.

• Yalnızca HTTPS protokolüne izin verilir.

• Localhost'a (geri döngü) erişime izin verilmiyor.

• IP adresleri kullanılamaz. DNS ad çözümlemesi gerektiren adlandırılmış bir web adresi kullanmanız gerekir.

• Sunucunuz, AzureCloud servis etiketi altında belirtilen Power Platform ve Dynamics 365 servisleri IP adresi değerlerinden bağlantılara izin vermelidir.

  Tip

  Geri arama çağrısı kimliği doğrulanamadığı için bazı önlemler alınmalıdır

  • Geri arama bildirimi alındığında akış oturumu kimliği geçerliliğini kontrol edin. Dataverse gerçeğin kaynağıdır.
  • Sunucu tarafınızda bir hız limiti stratejisi uygulayın.
  • Birkaç kuruluş arasında geri arama URL'si paylaşımını sınırlandırmayı deneyin.

Masaüstü akışı çalıştırması iptal etme

Tetik işlevine benzer olarak, sıraya alınmış/çalışır bir masaüstü akışını da iptal edebilirsiniz. Bir masaüstü akışını iptal etmek için CancelDesktopFlowRun eylemini kullanın.

Masaüstü akışını çalıştırmayı iptal etme isteği

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun HTTP/1.1  

Masaüstü akışını iptal etme isteğinden gelen yanıt

HTTP/1.1 204 No Content

Hatalar

Bir hata oluştuğunda, yanıtın Dataverse hata iletileriyle eşleşen farklı bir biçimi vardır. Http hata kodu ve iletisi, sorunu anlamak için yeterli bilgi sağlamalıdır.

HTTP/1.1 403 Forbidden

{
    "error": {
        "code": "0x80040220",
        "message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
    }
}