Retrieving capabilities IDs for declarative agent manifest

Articolo
09/16/2024

This article describes methods for developers to retrieve the necessary IDs to include Graph connectors and SharePoint/OneDrive files within the capabilities section of their declarative agent manifest. Developers can use Microsoft Graph Explorer or Microsoft Graph PowerShell.

Microsoft Graph connectors

This section describes how developers can retrieve the value to set in the connection_id property of the Connection object in the Microsoft Graph connectors object in the manifest.

Important

Querying for Microsoft Graph connectors requires an admin account.

Graph Explorer
PowerShell

Browse to Microsoft Graph Explorer and sign in with your admin account.
Select your user avatar in the upper right corner and select Consent to permissions.
Search for ExternalConnection.Read.All and select Consent for that permission. Follow the prompts to grant consent.
Enter https://graph.microsoft.com/v1.0/external/connections?$select=id,name in the request field and select Run query.

Locate the connector you want and copy its id property. For example, to use the GitHub Repos connector in the following response, copy the githubrepos value.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#connections(id,name)",
  "value": [
    {
      "id": "applianceparts",
      "name": "Appliance Parts Inventory"
    },
    {
      "id": "githubrepos",
      "name": "GitHub Repos"
    }
  ]
}

Copy the following code into a new file named GetGraphConnectorIds.ps1.

param(
    [Parameter(Mandatory = $false)]
    [Switch]
    $StayConnected = $false
)

# Requires an admin
Connect-MgGraph -Scopes "ExternalConnection.Read.All" `
    -UseDeviceCode -ErrorAction Stop -NoWelcome

Get-MgExternalConnection -Property "Name", "Id" | Format-Table "Name", "Id"

if ($StayConnected -eq $false) {
    Disconnect-MgGraph | Out-Null
    Write-Host "Disconnected from Microsoft Graph"
}
else {
    Write-Host
    Write-Host -ForegroundColor Yellow `
        "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Open PowerShell 7 in the directory where GetGraphConnectorIds.ps1 is located and run the script with the following command.
```
.\GetGraphConnectorIds.ps1
```
Open your browser and browse to https://microsoft.com/devicelogin. Enter the code that is provided by the prompt and complete the sign-in and consent flow.
```
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BQGGRREGN to authenticate.
```
Locate the connector you want and copy its Id property. For example, to use the GitHub Repos connector in the following response, copy the githubrepos value.
```
Name                      Id
----                      --
Appliance Parts Inventory applianceparts
GitHub Repos              githubrepos
```

Retrieving SharePoint IDs

This section describes how developers can retrieve the value to set in the following properties within the items_by_sharepoint_ids property of the OneDriveAndSharePoint object:

site_id
list_id
web_id
unique_id

Graph Explorer
PowerShell

Browse to Microsoft Graph Explorer and sign in with your admin account.
Select your user avatar in the upper right corner and select Consent to permissions.
Search for Sites.Read.All and select Consent for that permission. Follow the prompts to grant consent. Repeat this process for Files.Read.All.
Change the method dropdown to POST and enter https://graph.microsoft.com/v1.0/search/query in the request field.

Add the following in the Request body, replacing https://yoursharepointsite.com/sites/YourSite/Shared%20Documents/YourFile.docx with the URL to the file or folder you want to get IDs for.

{
  "requests": [
    {
      "entityTypes": [
        "driveItem"
      ],
      "query": {
        "queryString": "Path:\"https://yoursharepointsite.com/sites/YourSite/Shared%20Documents/YourFile.docx\""
      },
      "fields": [
        "fileName",
        "listId",
        "webId",
        "siteId",
        "uniqueId"
      ]
    }
  ]
}

Select Run query.

Locate the file you want and copy its listId, webId, siteId, and uniqueId properties.

{
  "value": [
    {
      "searchTerms": [],
      "hitsContainers": [
        {
          "hits": [
            {
              "hitId": "01AJOINAHZHINTBHPESZBISPIPSJG3D5EO",
              "rank": 1,
              "summary": "Reorder policy Our reorder policy for suppliers is straightforward and designed to maintain cost-efficiency and inventory control. We kindly request that no order exceeds a total",
              "resource": {
                "@odata.type": "#microsoft.graph.driveItem",
                "listItem": {
                  "@odata.type": "#microsoft.graph.listItem",
                  "id": "301b3af9-e49d-4296-893d-0f924db1f48e",
                  "fields": {
                    "fileName": "YourFile.docx",
                    "listId": "12fde922-4fab-4238-8227-521829cd1099",
                    "webId": "a25fab47-f3b9-4fa3-8ed9-1acb83c12a4f",
                    "siteId": "5863dfa5-b39d-4cd1-92a6-5cf539e04971",
                    "uniqueId": "{301b3af9-e49d-4296-893d-0f924db1f48e}"
                  }
                }
              }
            }
          ],
          "total": 1,
          "moreResultsAvailable": false
        }
      ]
    }
  ]
}

Copy the following code into a new file named GetSharePointIds.ps1.

param(
    [Parameter(Mandatory = $true,
    HelpMessage = "The URL path to the file or folder to search for")]
    [String]
    $FilePath,

    [Parameter(Mandatory = $false)]
    [Switch]
    $StayConnected = $false
)

Connect-MgGraph -Scopes "Sites.Read.All Files.Read.All" `
    -UseDeviceCode -ErrorAction Stop -NoWelcome

$searchQuery = @{
    requests = @(
        @{
            entityTypes = @("driveItem")
            query = @{
                queryString = "Path:""" + $FilePath +  """"
            }
            fields = @(
                "fileName"
                "listId"
                "webId"
                "siteId"
                "uniqueId"
            )
        }
    )
}

$results = Invoke-MgQuerySearch -Body $searchQuery

foreach($hitContainer in $results.HitsContainers)
{
    foreach($hit in $hitContainer.Hits)
    {
        Write-Output $hit.Resource.AdditionalProperties["listItem"]["fields"] | Format-Table
    }
}

if ($StayConnected -eq $false) {
    Disconnect-MgGraph | Out-Null
    Write-Host "Disconnected from Microsoft Graph"
}
else {
    Write-Host
    Write-Host -ForegroundColor Yellow `
        "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Open PowerShell 7 in the directory where GetSharePointIds.ps1 is located and run the script with the following command, replacing https://yoursharepointsite.com/sites/YourSite/Shared%20Documents/YourFile.docx with the URL to the file or folder you want to get IDs for.
```
.\GetSharePointIds.ps1 -FilePath "https://yoursharepointsite.com/sites/YourSite/Shared%20Documents/YourFile.docx"
```
Open your browser and browse to https://microsoft.com/devicelogin. Enter the code that is provided by the prompt and complete the sign-in and consent flow.
```
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BQGGRREGN to authenticate.
```

Locate the file you want and copy its values.

Key      Value
---      -----
fileName YourFile.docx
listId   12fde922-4fab-4238-8227-521829cd1099
webId    a25fab47-f3b9-4fa3-8ed9-1acb83c12a4f
siteId   5863dfa5-b39d-4cd1-92a6-5cf539e04971
uniqueId {301b3af9-e49d-4296-893d-0f924db1f48e}

Condividi tramite

Retrieving capabilities IDs for declarative agent manifest

Microsoft Graph connectors

Retrieving SharePoint IDs

Commenti e suggerimenti

Risorse aggiuntive