الاتصال وقطع اتصال Dataverse من مستودع Git باستخدام التعليمات البرمجية

استخدم واجهات ConnectToGit برمجة التطبيقات و DisconnectFromGit لدمج بيئة Microsoft Dataverse برمجيا مع التحكم في مصدر Git. باستخدام واجهات برمجة التطبيقات هذه، يمكنك توصيل الحلول الفردية أو البيئات بأكملها بمستودعات Git المدعومة وإدارة هذه الاتصالات من خلال التعليمات البرمجية.

المتطلبات المسبقه

قبل استخدام واجهات برمجة التطبيقات هذه، تأكد من أن لديك:

  • الوصول إلى بيئة Microsoft Dataverse
  • أذونات مسؤول النظام
  • الوصول للقراءة والكتابة إلى مستودع Git

ConnectToGit API

إنشاء اتصال بين حل أو بيئة Dataverse ومستودع Git. باستخدام هذا الاتصال، يمكنك إدارة التحكم بالمصادر لمكونات Dataverse.

إعدادات

ConnectToGit تقبل واجهة برمجة التطبيقات المعلمات التالية:

المعلمة النوع مطلوب الوصف
GitFolder السلسلة‬ ‏‏نعم‬ اسم المجلد الذي تريد ربط الحل أو البيئة به.
Branch السلسلة‬ ‏‏نعم‬ اسم الفرع الذي تريد الاتصال به.
ConnectionType رقم صحيح لا. تحديد ما يجب الاتصال به. راجع باراميتر ConnectionType.
GitProvider رقم صحيح لا. موفر Git. راجع معلمة GitProvider.
Organization السلسلة‬ لا. اسم المؤسسة التي تريد الاتصال بها.
Project السلسلة‬ لا. اسم المشروع الذي تريد الاتصال به.
Repository السلسلة‬ لا. اسم المستودع الذي تريد الاتصال به.
RootFolder السلسلة‬ لا. اسم المجلد الجذر حيث توجد جميع الحلول الخاصة بك في نطاق الحل.
SolutionUniqueName السلسلة‬ لا. الاسم الفريد للحل الذي ترغب في الاتصال به بـ Git.
UpstreamBranch السلسلة‬ لا. اسم الفرع المصدر الذي تريد الاتصال به. الإعدادات الافتراضية للفرع الافتراضي للمستودع.
GitHubConnectionId السلسلة‬ لا. معرف الاتصال لاتصال GitHub Power Platform. مطلوب عندما كان GitProvider1 ما لم توفّر GitHubPAT. لا يمكن استخدامه عند تمكين دعم الشبكة الظاهرية (VNET) لبيئة Dataverse.
GitHubPAT السلسلة‬ لا. رمز وصول شخصي في GitHub يتيح الوصول إلى المستودع المستهدف. مطلوب إذا كان GitProvider هو 1، إلا إذا قدمت GitHubConnectionId. مطلوب عند تمكين دعم الشبكة الظاهرية (VNET) لبيئة Dataverse.
GitHubAppConfigId السلسلة‬ لا. مرجع إلى سجل تكوين تطبيق GitHub. مطلوب إذا كان GitProvider هو 1. استخدم التنسيق githubappconfigs(<recordId>).

معلمة ConnectionType

تتحكم المعلمة ConnectionType في ما إذا كان يجب الاتصال ببيئة Dataverse بأكملها أو حل معين.

قيمة تسمية الوصف
1 الحل توصيل حل Dataverse محدد ب Git.
1 البيئة يربط بيئة Dataverse بأكملها ب Git.

معلمة GitProvider

استخدم المعلمة GitProvider لتحديد نوع موفر Git الذي تستخدمه، إما Azure DevOps أو GitHub.

قيمة تسمية الوصف
1 Azure DevOps استخدام للمستودعات المستضافة على Azure DevOps
1 GitHub استخدم للمستودعات المستضافة على GitHub

DisconnectFromGit API

إزالة اتصال Git من حل أو بيئة Dataverse، وتعطيل تكامل التحكم بالمصادر.

المعلمة

تحتوي DisconnectFromGit واجهة برمجة التطبيقات على معلمة واحدة فقط.

المعلمة النوع مطلوب الوصف
SolutionUniqueName السلسلة‬ لا. الاسم الفريد للحل الذي تريد قطع اتصاله ب Git. تجاهل لقطع اتصال جميع الحلول أو البيئة.

معلومات إضافية

فيما يلي بعض خيارات قيمة المعلمات لتحديدها عند استدعاء DisconnectFromGit.

  • فصل نظام واحد: استخدام SolutionUniqueName لفصل نظام معين.
  • قطع اتصال جميع الحلول: لا توفر أي معلمات لقطع اتصال كافة الاتصالات على مستوى الحل.
  • بيئة قطع الاتصال: لا توفر معلمات لقطع الاتصال على مستوى البيئة.

الأمثلة

تصف الأمثلة التالية سيناريوهات استخدام ConnectToGit واجهات برمجة التطبيقات و DisconnectFromGit :

توصيل بيئة Dataverse بأكملها بمستودع Azure DevOps

يتيح هذا الاتصال التحكم بالمصادر لكافة التكوينات والمكونات على مستوى البيئة.

لا تستخدم هذه المعلمات مع هذا الاتصال:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

يوضح هذا المثال كيفية استخدام إجراء ConnectToGit لتوصيل بيئة Dataverse بأكملها بمستودع Azure DevOps.

الطلب

POST [Organization URI]/api/data/v9.2/ConnectToGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "GitFolder": "yourGitfolderName",
   "Branch": "yourBranchName",
   "ConnectionType": 1,
   "GitProvider": 0,
   "Organization": "yourOrganizationName",
   "Project": "yourProjectName",
   "Repository": "yourRepositoryName"
}

استجابة

HTTP/1.1 204 No Content
OData-Version: 4.0

تعرف على كيفية استدعاء إجراءات واجهة برمجة تطبيقات الويب

الاتصال بمستودع GitHub

قبل استخدام واجهة برمجة التطبيقات للاتصال GitHub، أكمل خطوات الإعداد لإنشاء تطبيق GitHub، وتثبيته على المستودع الهدف، واستيراد مفتاحه الخاص إلى Azure Key Vault، وإنشاء اتصال power Platform GitHub. لمزيد من المعلومات، راجع الاتصال بـ GitHub.

إنشاء سجل تكوين تطبيق GitHub باستخدام واجهة برمجة تطبيقات الويب

استخدم Dataverse OData Web API لإنشاء githubappconfig سجل. أرسل طلب POST باستخدام معرف عميل GitHub App Key Vault URI واسم المفتاح.

يمكنك استخدام أي عميل HTTP، مثل Insomnia أو تعليمة Visual Studio برمجية REST Client أو curl لإجراء هذه المكالمات. تحتاج إلى رمز حامل للمصادقة. لمزيد من المعلومات، راجع استخدام واجهة برمجة تطبيقات الويب Microsoft Dataverse.

POST {{DataverseOrgUrl}}/api/data/v9.2/githubappconfigs
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "githubappid": "Iv23liBWoH9sf7xDrRe6",
    "keyvaulturi": "{{KeyVaultUri}}",
    "keyname": "demoGitHubKey"
}

مهم

لاحظ معرف السجل الذي تم إرجاعه في عنوان الاستجابة. تحتاج إلى هذه القيمة لتحديد الهوية المدارة وتكوين RBAC واستدعاء ConnectToGit. يستخدم معرف السجل تنسيقا مثل 13d565bb-4c22-f111-a546-7ced8d6e3e85.

بعد إنشاء سجل تكوين تطبيق GitHub، عيّن دور Key Vault Crypto User لهوية Dataverse المُدارة كما هو موضح فِي تكوين التحكم فِي الوصول المستند إلى الدور (RBAC) لـ Key Vault.

استدعاء واجهة برمجة التطبيقات ConnectToGit

بعد إنشاء githubappconfig السجل وتكوين Key Vault RBAC، استخدم واجهة برمجة تطبيقات ويب Dataverse لإنشاء اتصال التحكم بالمصادر عن طريق استدعاء ConnectToGit الإجراء.

POST {{DataverseOrgUrl}}/api/data/v9.2/ConnectToGit
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "GitProvider": 1,
    "ConnectionType": 1,
    "Organization": "YourGitHubOrg",
    "Repository": "YourRepo",
    "Project": "placeholder",
    "Branch": "yourBranch",
    "UpstreamBranch": "main",
    "GitFolder": "YourFolder",
    "GitHubConnectionId": "<connectionId>",
    "GitHubAppConfigId": "githubappconfigs(<recordId>)"
}

مهم

يجب أن يكون الفرع موجودا بالفعل في المستودع. قم بإنشائه في GitHub أولا إذا لزم الأمر. يجب أن تستخدم قيمة GitHubAppConfigId التنسيق githubappconfigs(<recordId>).

لقطة شاشة لنص طلب HTTP لواجهة برمجة تطبيقات ConnectToGit مع معلمات GitHub.

إذا تلقيت استجابة ناجحة، تكون البيئة متصلة GitHub.

الاتصال بمستودع GitHub باستخدام PowerShell

ينشئ مثال PowerShell التالي سجل تكوين تطبيق GitHub، وينتظر ظهور الهوية المدارة Dataverse في Microsoft Entra ID، ويعين دور Key Vault Crypto User للهوية المدارة، ويستدعي ConnectToGit الإجراء. إذا كان لديك بالفعل سجل لإعداد تطبيق GitHub، فأدخل GitHubAppConfigId لتخطي خطوات الإعداد وتعيين دور Key Vault.

قم بتثبيت وحدات PowerShell Az.Accounts وAz.KeyVault وAz.Resources واستيرادها قبل تشغيل المثال. سجل الدخول Connect-AzAccount باستخدام حساب لديه حق الوصول إلى بيئة Dataverse وإذن لتعيين أدوار Key Vault.

إذا تم تمكين دعم الشبكة الظاهرية (VNET) لبيئة Dataverse، فوفر GitHubPAT. لا يمكن استخدام اتصالات GitHub مع دعم الشبكة الظاهرية.

[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [string]$DataverseOrgUrl,

    [Parameter(Mandatory)]
    [string]$GitHubOrg,

    [Parameter(Mandatory)]
    [string]$GitHubRepo,

    [Parameter(Mandatory)]
    [string]$Branch,

    [Parameter(Mandatory)]
    [string]$GitFolder,

    [string]$GitHubAppClientId,

    [string]$KeyVaultName,

    [string]$KeyVaultKeyName,

    [string]$GitHubAppConfigId,

    [string]$GitHubConnectionId,

    [string]$GitHubPAT,

    [ValidateSet(0, 1)]
    [int]$ConnectionType = 1,

    [string]$UpstreamBranch,

    [string]$RootFolder,

    [string]$SolutionUniqueName
)

Set-StrictMode -Version 3.0
$ErrorActionPreference = "Stop"

if (($GitHubConnectionId -and $GitHubPAT) -or (-not $GitHubConnectionId -and -not $GitHubPAT)) {
    throw "Specify either -GitHubConnectionId or -GitHubPAT, but not both."
}

if (-not $GitHubAppConfigId) {
    foreach ($name in @('GitHubAppClientId', 'KeyVaultName', 'KeyVaultKeyName')) {
        if ([string]::IsNullOrWhiteSpace((Get-Variable -Name $name -ValueOnly))) {
            throw "Specify -$name when -GitHubAppConfigId is not provided."
        }
    }
}

$dataverseResource = $DataverseOrgUrl.TrimEnd('/')
$tokenResult = Get-AzAccessToken -ResourceUrl $dataverseResource -AsSecureString
$dataverseToken = [System.Net.NetworkCredential]::new('', $tokenResult.Token).Password

function Invoke-DataverseApi {
    param(
        [Parameter(Mandatory)]
        [string]$Method,

        [Parameter(Mandatory)]
        [string]$Endpoint,

        [object]$Body,

        [switch]$ReturnHeaders
    )

    $headers = @{
        Authorization      = "Bearer $dataverseToken"
        "OData-MaxVersion" = "4.0"
        "OData-Version"    = "4.0"
    }

    $request = @{
        Method      = $Method
        Uri         = "$dataverseResource/api/data/v9.2/$Endpoint"
        Headers     = $headers
        ContentType = "application/json; charset=utf-8"
    }

    if ($Body) {
        $request.Body = $Body | ConvertTo-Json -Depth 10
    }

    if ($ReturnHeaders) {
        return (Invoke-WebRequest @request).Headers
    }

    Invoke-RestMethod @request
}

$appConfigRecordId = $GitHubAppConfigId

if (-not $appConfigRecordId) {
    $keyVault = Get-AzKeyVault -VaultName $KeyVaultName
    $keyVaultUri = 'https://' + $KeyVaultName + '.vault.azure.net/'

    $appConfigBody = @{
        githubappid = $GitHubAppClientId
        keyvaulturi = $keyVaultUri
        keyname     = $KeyVaultKeyName
    }

    $responseHeaders = Invoke-DataverseApi `
        -Method POST `
        -Endpoint "githubappconfigs" `
        -Body $appConfigBody `
        -ReturnHeaders

    $entityIdHeader = [string]$responseHeaders["OData-EntityId"]
    if ($entityIdHeader -notmatch '\(([0-9a-f-]+)\)') {
        throw "Could not read the GitHub App configuration record ID from the Dataverse response."
    }

    $appConfigRecordId = $Matches[1]
    $managedIdentityName = "PPMI-githubappconfigmanagedidentity-$appConfigRecordId"

    $servicePrincipal = $null
    for ($attempt = 1; $attempt -le 60; $attempt++) {
        $servicePrincipal = Get-AzADServicePrincipal -DisplayName $managedIdentityName -ErrorAction SilentlyContinue
        if ($servicePrincipal) {
            break
        }

        Start-Sleep -Seconds 1
    }

    if (-not $servicePrincipal) {
        throw "The Dataverse managed identity was not found in Microsoft Entra ID. Check Dataverse System Jobs for GitHub App configuration errors."
    }

    $keyVaultScope = $keyVault.ResourceId
    if (-not $keyVaultScope) {
        $subscriptionId = (Get-AzContext).Subscription.Id
        $keyVaultScope = "/subscriptions/$subscriptionId/resourceGroups/$($keyVault.ResourceGroupName)/providers/Microsoft.KeyVault/vaults/$KeyVaultName"
    }

    $keyVaultCryptoUserRoleId = "12338af0-0e69-4776-bea7-57ae8d297424"
    $existingAssignment = Get-AzRoleAssignment `
        -ObjectId $servicePrincipal.Id `
        -RoleDefinitionId $keyVaultCryptoUserRoleId `
        -Scope $keyVaultScope `
        -ErrorAction SilentlyContinue

    if (-not $existingAssignment) {
        New-AzRoleAssignment `
            -ObjectId $servicePrincipal.Id `
            -RoleDefinitionId $keyVaultCryptoUserRoleId `
            -Scope $keyVaultScope | Out-Null
    }
}

$connectBody = @{
    GitProvider          = 1
    ConnectionType       = $ConnectionType
    Organization         = $GitHubOrg
    Repository           = $GitHubRepo
    Project              = "placeholder"
    Branch               = $Branch
    GitFolder            = $GitFolder
    GitHubAppConfigId    = "githubappconfigs($appConfigRecordId)"
}

if ($GitHubConnectionId) { $connectBody.GitHubConnectionId = $GitHubConnectionId }
if ($GitHubPAT)          { $connectBody.GitHubPAT          = $GitHubPAT }
if ($UpstreamBranch)     { $connectBody.UpstreamBranch     = $UpstreamBranch }
if ($RootFolder)         { $connectBody.RootFolder         = $RootFolder }
if ($SolutionUniqueName) { $connectBody.SolutionUniqueName = $SolutionUniqueName }

Invoke-DataverseApi -Method POST -Endpoint "ConnectToGit" -Body $connectBody
Write-Host "Connected Dataverse Git integration to GitHub."

افصل بيئة Dataverse الكاملة الخاصة بك عن التحكم في مصدر Git

يزيل هذا الإجراء اتصال Git على مستوى البيئة. لا تستخدم المعلمة SolutionUniqueName لهذه العملية. يقوم Dataverse تلقائيا بتعريف اتصال Git على مستوى البيئة وإزالته.

يوضح هذا المثال كيفية استخدام الإجراء DisconnectFromGit لقطع اتصال بيئة Dataverse بأكملها بالتحكم في مصدر Git.

الطلب

POST [Organization URI]/api/data/v9.2/DisconnectFromGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

استجابة

HTTP/1.1 204 No Content
OData-Version: 4.0

تعرف على كيفية استدعاء إجراءات واجهة برمجة تطبيقات الويب

توصيل الحل الأول بمستودع Git

ينشئ هذا الاتصال ارتباط المستودع وبنية المجلد للتحكم في المصدر على مستوى الحل إلى الحل الأول في بيئة.

تحتاج إلى تضمين قيم لهذه المعلمات لتحديد الحل:

  • RootFolder
  • SolutionUniqueName

يوضح هذا المثال كيفية استخدام إجراء ConnectToGit لتوصيل الحل الأول بمستودع Git.

الطلب

POST [Organization URI]/api/data/v9.2/ConnectToGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "GitFolder": "yourGitfolderName",
   "Branch": "yourBranchName",
   "ConnectionType": 1,
   "GitProvider": 0,
   "Organization": "yourOrganizationName",
   "Project": "yourProjectName",
   "Repository": "yourRepositoryName",
   "RootFolder": "yourRootFolderName",
   "SolutionUniqueName": "yourSolutionUniqueName"
}

استجابة

HTTP/1.1 204 No Content
OData-Version: 4.0

تعرف على كيفية استدعاء إجراءات واجهة برمجة تطبيقات الويب

توصيل حلول إضافية بنفس مستودع Git بعد توصيل الحل الأولي

بعد توصيل الحل الأول، تحتاج فقط إلى المعلمات الخاصة بالحل. ترث تفاصيل اتصال المستودع من الاتصال الأولي.

تعيين هذه المعلمات فقط:

  • SolutionUniqueName
  • Branch
  • GitFolder

مهم

يجب أولا توصيل الحل الأول قبل أن يعمل هذا. راجع توصيل الحل الأول بمستودع Git.

يوضح هذا المثال كيفية استخدام إجراء ConnectToGit لتوصيل الحلول اللاحقة بمستودع Git.

الطلب

POST [Organization URI]/api/data/v9.2/ConnectToGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "GitFolder": "yourGitfolderName",
   "Branch": "yourBranchName",
   "SolutionUniqueName": "yourSolutionUniqueName"
}

استجابة

HTTP/1.1 204 No Content
OData-Version: 4.0

تعرف على كيفية استدعاء إجراءات واجهة برمجة تطبيقات الويب

قطع اتصاَلْ حل معين مِنْ اَلْتحكم فِي مصدر Git مع إبقاء اَلْحلول اَلْأخرى متصلة

استخدم هذا الأسلوب لإزالة التحكم بالمصادر لأحد الحلول دون التأثير على الآخرين.

يوضح هذا المثال كيفية استخدام الإجراء DisconnectFromGit لإزالة التحكم بالمصادر لأحد الحلول دون التأثير على الآخرين.

الطلب

POST [Organization URI]/api/data/v9.2/DisconnectFromGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "SolutionUniqueName": "yourSolutionUniqueName"
}

استجابة

HTTP/1.1 204 No Content
OData-Version: 4.0

تعرف على كيفية استدعاء إجراءات واجهة برمجة تطبيقات الويب

معالجة الأخطاء

لا ترجع ConnectToGit واجهة برمجة التطبيقات ولا DisconnectFromGit قيمة عند اكتمالها بنجاح. عندما تفشل واجهة برمجة التطبيقات، فإنها ترجع خطأ.

تتضمن سيناريوهات الخطأ الشائعة ما يلي:

  • بيانات الاعتماد غير الصالحة: تأكد من أن لديك مصادقة صالحة لموفر Git.
  • لم يتم العثور على المستودع: تحقق من أسماء المؤسسة والمشروع والمستودع.
  • تم رفض الإذن: تأكد من أن حساب Dataverse الخاص بك لديه أذونات إدارة التحكم بالمصادر.
  • لم يتم العثور على الحل: تحقق من SolutionUniqueName وجود في بيئتك.
  • الفرع غير موجود: تأكد من وجود الفرع المحدد في المستودع.

الدعم والموارد الإضافية

لمزيد من المعلومات حول تكامل التحكم بالمصادر مع Dataverse، راجع:

  • Last updated on