Chia sẻ qua

Cập nhật và xóa các hàng trong bảng bằng API Web

Các thao tác sửa đổi dữ liệu là một phần cốt lõi của API Web. Ngoài các thao tác cập nhật và xóa đơn giản, bạn có thể thực hiện các thao tác trên các cột bảng đơn lẻ (thuộc tính thực thể) và soạn các yêu cầu upsert sẽ cập nhật hoặc chèn dữ liệu tùy thuộc vào việc dữ liệu đó có tồn tại hay không.

Cập nhật cơ bản

Các hoạt động cập nhật sử dụng động từ HTTP PATCH . Chuyển một đối tượng JSON chứa các thuộc tính bạn muốn cập nhật vào URI đại diện cho bản ghi. Phản hồi có trạng thái sẽ 204 No Content được trả về nếu cập nhật thành công.

If-Match: * Tiêu đề đảm bảo bạn không tạo bản ghi mới bằng cách vô tình thực hiện thao tác upsert. Thông tin thêm: Ngăn tạo trong upsert.

Quan trọng

Khi cập nhật một thực thể, chỉ bao gồm các thuộc tính bạn đang thay đổi trong nội dung yêu cầu. Chỉ cần cập nhật các thuộc tính của một thực thể mà bạn đã truy xuất trước đó và bao gồm JSON đó trong yêu cầu của bạn, sẽ cập nhật từng thuộc tính mặc dù giá trị giống nhau. Điều này có thể gây ra các sự kiện hệ thống có thể kích hoạt logic nghiệp vụ mong đợi rằng các giá trị đã thay đổi. Điều này có thể khiến các thuộc tính dường như đã được cập nhật trong dữ liệu kiểm tra trong khi thực tế chúng không thực sự thay đổi.

Khi bạn cập nhật thuộc statecode tính, điều quan trọng là phải luôn đặt mong muốn statuscode. statecode và statuscode có các giá trị phụ thuộc. Có thể có nhiều giá trị hợp lệ statuscode cho một giá trị nhất định statecode , nhưng mỗi statecode cột có một giá trị DefaultStatus duy nhất được đặt cấu hình. Khi bạn cập nhật statecode mà không chỉ định a statuscode, giá trị trạng thái mặc định sẽ được hệ thống đặt. Ngoài ra, khi kiểm tra được bật trên bảng và statuscode cột, giá trị đã thay đổi cho statuscode cột sẽ không được ghi lại trong dữ liệu kiểm tra trừ khi nó được chỉ định trong thao tác cập nhật.

Lưu ý

Định nghĩa cho các thuộc tính bao gồm một RequiredLevel thuộc tính. Khi điều này được đặt thành SystemRequired, bạn không thể đặt các thuộc tính này thành giá trị rỗng. Thông tin thêm: Cấp yêu cầu thuộc tính

Ví dụ này cập nhật bản ghi tài khoản hiện có với accountid giá trị 00000000-0000-0000-0000-000000000001.

Lời yêu cầu:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}

Phản ứng:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Lưu ý

Xem Sử dụng thuộc tính điều hướng có giá trị đơn để biết thông tin về cách liên kết và hủy liên kết các thực thể khi cập nhật.

Cập nhật với dữ liệu được trả về

Để truy xuất dữ liệu từ một thực thể bạn đang cập nhật, bạn có thể soạn yêu cầu của mình PATCH để dữ liệu từ bản ghi đã tạo được trả về với trạng thái 200 (OK). Để có được kết quả này, bạn phải sử dụng Prefer: return=representation tiêu đề yêu cầu.

Để kiểm soát thuộc tính nào được trả về, hãy $select thêm tùy chọn truy vấn vào URL vào tập hợp thực thể. $expand Tùy chọn truy vấn bị bỏ qua nếu được sử dụng.

Ví dụ này cập nhật thực thể tài khoản và trả về dữ liệu được yêu cầu trong phản hồi.

Lời yêu cầu:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
Prefer: return=representation
If-Match: * 
  
{"name":"Updated Sample Account"}

Phản ứng:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
Preference-Applied: return=representation  
OData-Version: 4.0  
  
{  
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",  
    "@odata.etag": "W/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}

Cập nhật nhiều bản ghi trong một yêu cầu

Cách nhanh nhất để cập nhật nhiều bản ghi cùng loại trong một yêu cầu là sử dụng hành động UpdateMulti. Tại thời điểm viết bài này, hành động UpdateMulti. Không phải tất cả các bảng tiêu chuẩn đều hỗ trợ hành động này, nhưng tất cả các bảng đàn hồi đều hỗ trợ.

Thông tin khác:

Cập nhật một giá trị thuộc tính

Khi bạn chỉ muốn cập nhật một giá trị thuộc tính duy nhất, hãy sử dụng yêu PUT cầu có tên thuộc tính được thêm vào Uri của thực thể.

Ví dụ sau đây cập nhật name thuộc tính của một hàng hiện có account với accountid giá trị 00000000-0000-0000-0000-000000000001.

Lời yêu cầu:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}

Phản ứng:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Xóa một giá trị thuộc tính

Để xóa giá trị của một thuộc tính, hãy sử dụng yêu DELETE cầu có tên thuộc tính được thêm vào Uri của thực thể.

Ví dụ sau đây xóa giá trị của description thuộc tính của thực thể tài khoản có accountid giá trị 00000000-0000-0000-0000-00000000001.

Lời yêu cầu:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Phản ứng:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Lưu ý

Không thể sử dụng tính năng này với thuộc tính điều hướng có giá trị đơn để hủy liên kết hai thực thể. Để biết cách tiếp cận thay thế, hãy xem bài viết Hủy liên kết với thuộc tính điều hướng có giá trị đơn .

Upsert một hàng bảng

Hoạt động upsert tương tự như một bản cập nhật. Nó sử dụng một PATCH yêu cầu và sử dụng URI để tham chiếu một bản ghi cụ thể. Sự khác biệt là nếu bản ghi không tồn tại, nó sẽ được tạo. Nếu nó đã tồn tại, nó sẽ được cập nhật.

Upsert có giá trị khi đồng bộ hóa dữ liệu giữa các hệ thống bên ngoài. Hệ thống bên ngoài có thể không chứa tham chiếu đến khóa chính của bảng Dataverse, vì vậy bạn có thể đặt cấu hình các khóa thay thế cho bảng Dataverse bằng cách sử dụng các giá trị từ hệ thống bên ngoài xác định duy nhất bản ghi trên cả hai hệ thống. Thông tin thêm: Xác định khóa thay thế cho các hàng tham chiếu

Bạn có thể thấy bất kỳ khóa thay thế nào được xác định cho bảng trong chú thích cho loại thực thể trong tài liệu dịch vụ $metadata. Thông tin thêm: Khóa thay thế.

Trong ví dụ sau, có một bảng có tên sample_thing có khóa thay thế tham chiếu đến hai cột: sample_key1 và sample_key2, cả hai đều được xác định để lưu trữ các giá trị số nguyên.

Lời yêu cầu:

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

Đối với cả thao tác tạo hoặc cập nhật, bạn sẽ nhận được cùng một phản hồi. Lưu ý cách OData-EntityId tiêu đề phản hồi sử dụng các giá trị khóa thay vì mã định danh khóa chính GUID cho bản ghi.

Phản ứng:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Vì phản hồi giống nhau, bạn không thể biết liệu hoạt động có đại diện cho hoạt động hoặc CreateUpdate hay không.

Nếu bạn cần biết, bạn có thể sử dụng Prefer: return=representation tiêu đề yêu cầu. Với tiêu đề này, bạn sẽ nhận được 201 Created phản hồi khi bản ghi được tạo và 200 OK phản hồi khi bản ghi được cập nhật. Tùy chọn này thêm một Retrieve hoạt động, có tác động đến hiệu suất. Nếu bạn sử dụng Prefer: return=representation tiêu đề yêu cầu, hãy đảm bảo rằng bạn $select bao gồm lượng dữ liệu tối thiểu, tốt nhất là chỉ cột khóa chính. Thông tin thêm: Cập nhật với dữ liệu được trả về và Tạo với dữ liệu được trả về.

Khi sử dụng khoá thay thế, bạn không nên bao gồm các giá trị khoá thay thế trong nội dung của yêu cầu.

  • Khi một upsert đại diện cho một Update, các giá trị khóa thay thế này sẽ bị bỏ qua. Bạn không thể cập nhật các giá trị khóa thay thế trong khi sử dụng chúng để xác định bản ghi.
  • Khi một upsert đại diện cho một Create, các giá trị khóa trong URL được đặt cho bản ghi nếu chúng không có trong nội dung. Vì vậy, không cần phải đưa chúng vào nội dung của yêu cầu.

Thông tin thêm: Sử dụng Upsert để tạo hoặc cập nhật bản ghi

Lưu ý

Thông thường khi tạo một bản ghi mới, bạn sẽ để hệ thống gán giá trị GUID cho khóa chính. Đây là phương pháp hay nhất vì hệ thống tạo ra các khóa được tối ưu hóa cho chỉ mục và điều này giúp cải thiện hiệu suất. Nhưng nếu bạn cần tạo một bản ghi với một giá trị khóa chính cụ thể, chẳng hạn như khi giá trị GUID khóa được tạo bởi một hệ thống bên ngoài, thao tác sẽ upsert cung cấp một cách để thực hiện việc này.

Ngăn tạo hoặc cập nhật bằng upsert

Đôi khi có những tình huống bạn muốn thực hiện một upsert, nhưng bạn muốn ngăn chặn một trong các thao tác tiềm năng: tạo hoặc cập nhật. Bạn có thể thực hiện việc này bằng cách sử dụng If-Match tiêu đề or If-None-Match . Để biết thêm thông tin, hãy xem Giới hạn hoạt động upsert.

Xóa cơ bản

Thao tác xóa rất đơn giản. Sử dụng DELETE động từ với URI của thực thể bạn muốn xóa. Thông báo ví dụ này xóa một thực thể tài khoản có giá trị khóa accountid chính bằng 000000000-0000-0000-0000-00000000001.

Lời yêu cầu:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Phản ứng:

Nếu thực thể tồn tại, bạn sẽ nhận được phản hồi bình thường với trạng thái 204 để cho biết việc xóa đã thành công. Nếu không tìm thấy thực thể, bạn sẽ nhận được phản hồi với trạng thái 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Kiểm tra các bản ghi trùng lặp

Để biết thêm thông tin về cách kiểm tra các bản ghi trùng lặp trong quá trình cập nhật, hãy xem Phát hiện các bản ghi trùng lặp trong quá trình Cập nhật bằng API Web.

Xóa nhiều bản ghi trong một yêu cầu

Cách nhanh nhất để xóa nhiều bản ghi cùng loại trong một yêu cầu là sử dụng DeleteMultiple hành động. Tại thời điểm viết bài này, hành động là DeleteMultiple tính năng xem trước. Các bảng tiêu chuẩn không hỗ trợ hành động này, nhưng tất cả các bảng đàn hồi đều hỗ trợ.

Lưu ý

Đối với bảng tiêu chuẩn, chúng tôi khuyên bạn nên sử dụng hành động BulkDelete, cho phép xóa không đồng bộ các bản ghi khớp với truy vấn. Thông tin thêm: Xóa hàng loạt dữ liệu

Thông tin khác:

Cập nhật và xóa tài liệu trong phân vùng lưu trữ

Nếu bạn đang cập nhật hoặc xóa dữ liệu bảng đàn hồi được lưu trữ trong phân vùng, hãy đảm bảo chỉ định khóa phân vùng khi truy cập dữ liệu đó.

Thông tin thêm: Chọn giá trị PartitionId

Xem thêm

Mẫu hoạt động cơ bản của API Web (C#)
Mẫu hoạt động cơ bản API Web (JavaScript phía máy khách)
Thực hiện các thao tác bằng API Web
Soạn các yêu cầu Http và xử lý lỗi
Truy vấn dữ liệu bằng API Web
Tạo hàng bảng bằng cách sử dụng API Web
Truy xuất hàng bảng bằng API Web
Liên kết và hủy liên kết các hàng trong bảng bằng API Web
Sử dụng các chức năng API Web
Sử dụng các hành động của Web API
Thực hiện các hoạt động hàng loạt bằng API Web
Mạo danh người dùng khác bằng API Web
Thực hiện các thao tác có điều kiện bằng API Web

  • Last updated on