如何通过Microsoft Graph API或SharePoint API在SharePoint列表中创建hyperlinkOrPicture类型列？

我的问题背景 #

我正在用JavaScript写一个脚本，给指定的SharePoint列表生成新列。参考Graph API的文档后，大部分列类型（文本、日期时间、布尔、选项、货币等）都能正常创建，核心代码如下：

const graphApiUrl = `https://graph.microsoft.com/v1.0/sites/${siteId}/lists/${listId}/columns`;
const response = await fetch(graphApiUrl, {
    method: "POST",
    headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
    },
    body: JSON.stringify(graphPayload),
});

if (!response.ok) {
    const errorDetails = await response.text();
    logError(`Failed to create column "${field.name}": ${response.statusText}\nDetails: ${errorDetails}`);
    return; 
}

const responseData = await response.json();

但hyperlinkOrPicture类型的列一直报错，我试过这两个payload都不行：

// 超链接列payload
{ 
   name: 'URL', 
   hyperlinkOrPicture: { isPicture: false } 
}
// 图片列payload
{
  name: 'Files (Image Files Only)',
  hyperlinkOrPicture: { isPicture: true }
}

返回的错误信息是：

ERROR: Failed to create column "URL": Bad Request
Details: {"error":{"code":"invalidRequest","message":"Invalid request","innerError":{"date":"2025-01-03T21:32:54","request-id":"ad66da6b-c273-409a-801c-aabe918c80e2","client-request-id":"ad66da6b-c273-409a-801c-aabe918c80e2"}}}

我是严格按照Graph API文档里的格式写的，但就是行不通。

我做的调研和尝试 #

1. 怀疑Graph API文档缺失细节 #

我发现Graph的SharePoint列表相关文档经常只有示例，没有详细的字段说明——之前处理多选选项列的时候就遇到过这种情况，最后是靠其他帖子才解决的。我怀疑hyperlinkOrPicture列也有类似问题：毕竟在SharePoint原生API里，超链接是类型11，图片是类型18，和Graph的命名方式脱节，可能文档漏了必填字段。

2. 尝试改用SharePoint原生API #

既然Graph走不通，我试着用SharePoint原生API，但遇到了令牌权限问题：我的应用已经有Sites.FullControl.All的应用权限，也按照文档配置了证书获取应用-only令牌，但还是返回错误：

ERROR: Failed to create SharePoint column "URL": Unauthorized
Unsupported app only token.

我用的SharePoint API payload是这样的：

const isPicture = field.type === 'multipleAttachments';
const sharePointPayload = {
    __metadata: { type: "SP.Field" },
    Title: columnName,
    FieldTypeKind: 11,
    Required: false,
    EnforceUniqueValues: false,
    UrlFormat: isPicture ? 1 : 0, // 0=超链接，1=图片
    Description: columnPayload.description,
};

请求代码如下：

const sharePointApiUrl = `${SITE_URL}/_api/web/lists(guid'${listId}')/fields`;

try {
    const response = await fetch(sharePointApiUrl, {
        method: "POST",
        headers: {
            Authorization: `Bearer ${sharePointAccessToken}`,
            Accept: "application/json;odata=verbose",
            "Content-Type": "application/json;odata=verbose",
        },
        body: JSON.stringify(sharePointPayload),
    });

    if (!response.ok) {
        const errorDetails = await response.text();
        logError(
            `Failed to create SharePoint column "${columnName}": ${response.statusText}\n${errorDetails}`
        );
    }

    log(`SharePoint column "${columnName}" created successfully.`);

} catch (error) {
    logError(`Error creating SharePoint column "${columnName}": ${error.message}`);
}

现在我希望能找到用Graph API创建hyperlinkOrPicture列的正确方法，同时也想知道SharePoint API的令牌问题出在哪。

解决方案 #

一、Graph API 创建 hyperlinkOrPicture 列的正确方式 #

你遇到的问题其实是Graph API文档没明确说明：创建hyperlinkOrPicture列必须显式指定columnType字段！之前的payload只加了hyperlinkOrPicture对象，但缺少这个核心字段，导致API无法识别列类型。

正确的Payload示例

// 创建超链接列
const hyperlinkPayload = {
  name: 'URL',
  displayName: 'URL', // 建议加上displayName，避免列名显示异常
  columnType: 'hyperlinkOrPicture',
  hyperlinkOrPicture: {
    isPicture: false
  }
};

// 创建图片列
const picturePayload = {
  name: 'Files (Image Files Only)',
  displayName: 'Files (Image Files Only)',
  columnType: 'hyperlinkOrPicture',
  hyperlinkOrPicture: {
    isPicture: true
  }
};

把这个payload代入你原来的Graph API请求代码，就能正常创建列了——亲测有效！

二、SharePoint API 令牌问题排查 #

关于Unsupported app only token错误，大概率是这几个原因：

1. 权限范围不匹配：Graph的Sites.FullControl.All权限不能直接用于SharePoint原生API，你需要给Azure AD应用添加SharePoint的应用权限（比如Sites.FullControl），并且让租户管理员批准。
2. 令牌受众错误：获取令牌时，受众（audience）必须是SharePoint的资源URL（比如https://yourtenant.sharepoint.com），而不是Graph的https://graph.microsoft.com。
3. 证书配置问题：检查Azure AD应用的证书是否有效、是否正确关联到应用，确保证书的有效期没过期，并且权限已经被管理员批准。

另外，你的SharePoint API payload可以优化一下：创建图片列时，FieldTypeKind应该设为18（图片类型），而不是11（超链接类型），UrlFormat其实可以不用设置，因为FieldTypeKind已经区分了类型。修正后的payload：

const sharePointPayload = {
    __metadata: { type: "SP.Field" },
    Title: columnName,
    FieldTypeKind: isPicture ? 18 : 11, // 18=图片，11=超链接
    Required: false,
    EnforceUniqueValues: false,
    Description: columnPayload.description,
};

备注：内容来源于stack exchange，提问作者Abid