Onayları yönetme

Bu belgede, Google Drive API'sinde onayların nasıl yönetileceği açıklanmaktadır.

Kullanıcılar, Google Drive'daki dokümanları resmi onay sürecine gönderebilir. Bu süreçten, sözleşme incelemelerini veya resmi belgeleri yayınlanmadan önce onaylatmak için yararlanabilirsiniz. Onay, hem incelemenin (ör. Devam Ediyor, Onaylandı veya Reddedildi) hem de ilgili incelemecilerin durumunu takip eder. Onaylar, içerikleri doğrulamak ve inceleme yapan kullanıcıların kaydını tutmak için mükemmel bir yöntemdir.

Drive'da içerik onayları oluşturup yönetebilirsiniz. Google Drive API, dosya onaylarıyla çalışmak için approvals kaynağını sağlar. approvals kaynağının yöntemleri Drive, Google Dokümanlar ve diğer Google Workspace düzenleyicilerindeki öğelerde çalışır. İncelemeciler, dokümanları doğrudan onaylayabilir, reddedebilir veya bu dokümanlara geri bildirim ekleyebilir.

Başlamadan önce

  1. Dosyanızda canStartApproval özelliği bulunmalıdır . Dosya özelliklerini kontrol etmek için files kaynağında get yöntemini fileId yol parametresiyle çağırın ve fields parametresinde canStartApproval özellik alanını kullanın. Daha fazla bilgi için Dosya özelliklerini anlama başlıklı makaleyi inceleyin.

    Boole canStartApproval özelliği şu durumlarda false olur:

    • Yönetici ayarları, özelliğe erişimi kısıtlıyor.
    • Google Workspace sürümünüz uygun değil.
    • Dosya, alanınızın dışındaki bir kullanıcıya aitse
    • Kullanıcının dosya üzerinde role=writer izni yok.

  2. Hedef dosyayı incelemecilerle manuel olarak paylaştığınızdan emin olun. Drive bunu otomatik olarak yapmaz. İnceleyenin dosya erişimi yoksa onay isteği başarılı olur ancak inceleyen bildirim almaz veya dosyayı görüntüleyemez.

Kavramlar

Aşağıdaki temel kavramlar, onayların temelini oluşturur.

Onay durumu

Doküman onayı istediğinizde onay süreci, her incelemecinin dokümanla ilgili geri bildirimde bulunabilmesini sağlar.

approvals kaynağı, kaynak istendiğinde onayın durumunu ayrıntılı olarak açıklayan bir Status nesnesi içerir. Ayrıca, belirli yorumcuların onaylarına verilen yanıtları ayrıntılı olarak açıklayan ReviewerResponse nesnesini de içerir. Her yorumcunun yanıtı Response nesnesiyle gösterilir.

Dosya içeriği, onay Status IN_PROGRESS durumundayken değiştirildiğinde onayın davranışı, fileContentChangeBehavior alanıyla belirlenir.approvals Aşağıdaki davranışlar uygulanabilir:

  • RESET_APPROVAL: Onay süreci, her inceleme uzmanının içeriğin aynı sürümünü onaylamasını sağlar. Dosya, bir incelemeci isteği onayladıktan sonra ve istek tamamlanmadan önce düzenlenirse incelemecinin onayları sıfırlanır (yanıt NO_RESPONSE olarak ayarlanır) ve incelemecilerin yeni sürümü onaylaması gerekir. Onay durumu APPROVED olduğunda, dosya üzerinde başka değişiklik yapılmasını önlemek için kilitlenir. Nihai onaydan sonra yapılan ek içerik düzenlemeleri, belgede mevcut sürümün onaylı sürümden farklı olduğunu belirten bir banner'ın görünmesine neden olur. Bu, varsayılan davranıştır.

  • NO_APPROVAL_ACTION: Dosya içeriğinde yapılan düzenlemeler, onay beklenirken inceleyen kararlarını sıfırlamaz. Ayrıca, dosya nihai onayda kilitlenmez. İnceleme yapan kişiler, onay tamamlanmadan önce istedikleri zaman kendi APPROVED kararlarını beklemede durumuna (yanıt NO_RESPONSE olarak ayarlanır) sıfırlayabilir.

Onay tamamlandıktan sonra bu davranış artık geçerli olmaz.

Onay sürecindeki her işlem, onay isteyen kullanıcıya ve tüm inceleme uzmanlarına e-posta bildirimi gönderir. Ayrıca onay etkinliği günlüğüne de eklenir.

Tüm incelemecilerin onayı onaylaması gerekir. Onayı reddeden tüm incelemeciler, tamamlanma durumunu DECLINED olarak ayarlar.

Onay tamamlandıktan sonra (durum APPROVED, CANCELLED veya DECLINED olduğunda) tamamlanmış durumda kalır ve başlatıcı ya da inceleme uzmanları tarafından etkileşimde bulunulamaz. Durumu IN_PROGRESS olan bir dosyada mevcut onay olmadığı sürece tamamlanmış bir onaya yorum ekleyebilirsiniz.

Onayların yaşam döngüsü

Onayların yaşam döngüsü.
Şekil 1. Onayların yaşam döngüsü.

Bir onay, yaşam döngüsü boyunca çeşitli durumlardan geçer. Şekil 1'de onay yaşam döngüsünün üst düzey adımları gösterilmektedir:

  1. Onay sürecini başlatın. Onay isteğini başlatmak için start numaralı telefonu arayın. status, IN_PROGRESS olarak ayarlanır.

  2. Onay bekleniyor. Onay beklerken (status, IN_PROGRESS olarak ayarlanmışken) hem başlatıcı hem de inceleyenler onay isteğiyle etkileşim kurabilir. comment ekleyebilir, başlatıcı reassign incelemeciler ve bir veya daha fazla incelemeci isteği approve edebilir.

  3. Onay tamamlandı durumundadır. Bir onay, tüm incelemeciler isteği onayladığında, isteği başlatan kişi isteği cancel seçtiğinde veya herhangi bir incelemeci isteği decline seçtiğinde tamamlandı durumuna (status, APPROVED, CANCELLED veya DECLINED olarak ayarlanır) geçer.

Alanlar parametresini kullanma

Yanıt içinde döndürülecek alanları belirtmek istiyorsanız fields system parametresini approvals kaynağının herhangi bir yöntemiyle ayarlayabilirsiniz. fields parametresini atlarsanız sunucu, yönteme özgü varsayılan bir alan kümesi döndürür. Farklı alanlar döndürmek için Belirli alanları döndürme başlıklı makaleye bakın.

Onay başlatma ve yönetme

approvals kaynağı, Drive API'yi kullanarak onayları başlatmak ve yönetmek için kullanılabilir. Bu yöntemler, dosya meta verilerinin yazılmasına izin veren mevcut OAuth 2.0 Drive API kapsamlarından herhangi biriyle çalışır. Daha fazla bilgi için Google Drive API kapsamlarını seçme başlıklı makaleyi inceleyin.

Onay başlatma

Bir dosyada yeni bir onay başlatmak için approvals kaynağında start yöntemini kullanın ve fileId yol parametresini ekleyin.

İstek gövdesi, dosyayı incelemekle görevlendirilen inceleme uzmanlarının e-posta adreslerini içeren bir diziden oluşan zorunlu reviewerEmails alanını içerir. Her inceleme uzmanının e-posta adresi bir Google Hesabı ile ilişkilendirilmelidir. Aksi takdirde istek başarısız olur. Ayrıca dört isteğe bağlı alan sunulur:

  • dueTime: RFC 3339 biçiminde onay için son tarih.
  • lockFile: Onay başlatıldığında dosyanın kilitlenip kilitlenmeyeceğini belirten bir Boole değeri. Bu işlem, kullanıcıların onay süreci sırasında dosyayı değiştirmesini engeller. role=writer iznine sahip herhangi bir kullanıcı bu kilidi kaldırabilir.
  • message: Yorumculara gönderilen özel mesaj.
  • fileContentChangeBehavior: Dosya içeriği değiştiğinde onayın davranışı. Desteklenen değerler:
    • RESET_APPROVAL: (Varsayılan) Onay işlemi devam ederken içerik değiştiğinde APPROVED değerindeki tüm inceleyen yanıtlarını NO_RESPONSE olarak sıfırlar. Onay APPROVED durumuyla tamamlandığında dosya kilitlenir.
    • NO_APPROVAL_ACTION: İçerik değiştiğinde inceleyenlerin yanıtlarını sıfırlamaz ve onay tamamlandığında dosyayı kilitlemez.

Yanıt gövdesinde approvals kaynağının bir örneği bulunur ve bu örnek, onayı isteyen kullanıcı olan initiator alanını içerir. Onay Status, IN_PROGRESS olarak ayarlanmış olmalıdır.

Status değeri IN_PROGRESS olan mevcut bir onay varsa start yöntemi başarısız olur. Yalnızca dosyada mevcut bir onay yoksa veya mevcut onay tamamlandı durumundaysa (durum APPROVED, CANCELLED veya DECLINED) onay başlatabilirsiniz.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval.",
    "fileContentChangeBehavior": "RESET_APPROVAL"
 }'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.

Onayla ilgili yorum yapma

Bir onayı yorumlamak için approvals kaynağında comment yöntemini kullanın ve fileId ile approvalId yol parametrelerini ekleyin.

İstek gövdesi, onaya eklemek istediğiniz yorumu içeren bir dize olan zorunlu message alanından oluşur.

Yanıt metni, approvals kaynağının bir örneğini içerir. İleti, onay başlatıcıya ve inceleyenlere bildirim olarak gönderilir ve onay etkinliği günlüğüne de eklenir.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • APPROVAL_ID: Onayın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.

Onayda inceleme ekibini yeniden atama

Bir onaydaki incelemecileri yeniden atamak için approvals kaynağında reassign yöntemini kullanın ve fileId ile approvalId yol parametrelerini ekleyin.

reassign yöntemi, onay başlatıcının (veya role=writer iznine sahip bir kullanıcının) approvals kaynağının ReviewerResponse nesnesine inceleyenler eklemesine veya inceleyenleri değiştirmesine olanak tanır. role=reader iznine sahip bir kullanıcı yalnızca kendisine atanmış bir onayı yeniden atayabilir. Bu sayede kullanıcı, isteği daha yetkin bir incelemeciye yeniden atayabilir.

İncelemeciler yalnızca Status IN_PROGRESS durumundayken ve yeniden atanan incelemecinin response alanı NO_RESPONSE olarak ayarlanmışken yeniden atanabilir.

Onaylarda incelemeci kaldıramayacağınızı unutmayın. Bir incelemeciyi kaldırmanız gerekiyorsa onayı iptal edip yeni bir onay başlatmanız gerekir.

İstek gövdesi, isteğe bağlı addReviewers ve replaceReviewers alanlarından oluşur. Her alan, AddReviewer ve ReplaceReviewer için tekrarlanan bir nesneye sahiptir. Bu nesnelerin her biri, eklenecek tek bir incelemeci veya değiştirilecek bir çift incelemeci içerir. Yeni inceleme uzmanlarına göndermek istediğiniz yorumu içeren isteğe bağlı message alanını da ekleyebilirsiniz.

Yanıt metni, approvals kaynağının bir örneğini içerir. Mesaj, yeni inceleme uzmanlarına bildirim olarak gönderilir ve onay etkinliği günlüğüne de eklenir.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • APPROVAL_ID: Onayın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.

Onayı iptal etme

Bir onayı iptal etmek için approvals kaynağında cancel yöntemini kullanın ve fileId ile approvalId yol parametrelerini ekleyin.

cancel yöntemi yalnızca onay başlatıcı (veya role=writer iznine sahip bir kullanıcı) tarafından Status onayı IN_PROGRESS durumundayken çağrılabilir.

İstek gövdesi, onayın iptal edilmesine eşlik edecek mesajı içeren bir dize olan isteğe bağlı message alanından oluşur.

Yanıt metni, approvals kaynağının bir örneğini içerir. İleti, bildirim olarak gönderilir ve onay etkinliği günlüğüne de eklenir. Onay Status, CANCELLED olarak ayarlanmış ve tamamlanmış durumda.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • APPROVAL_ID: Onayın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.

Onayı reddetme

Bir onayı reddetmek için approvals kaynağında decline yöntemini kullanın ve fileId ile approvalId yol parametrelerini ekleyin.

decline yöntemi yalnızca onay Status IN_PROGRESS durumundayken çağrılabilir.

İstek gövdesi, onayın reddedilmesine eşlik edecek mesajı içeren bir dize olan isteğe bağlı message alanından oluşur.

Yanıt metni, approvals kaynağının bir örneğini içerir. İleti, bildirim olarak gönderilir ve onay etkinliği günlüğüne de eklenir. İstek gönderen kullanıcının response alanı, ReviewerResponse nesnesinde DECLINED olarak ayarlanır. Ayrıca, onay Status, DECLINED olarak ayarlanır ve tamamlanmış durumdadır.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • APPROVAL_ID: Onayın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.

Onayı onayla

Bir onayı onaylamak için approvals kaynağında approve yöntemini kullanın ve fileId ile approvalId yol parametrelerini ekleyin.

approve yöntemi yalnızca onay Status IN_PROGRESS durumundayken çağrılabilir.

İstek gövdesi, onaya eşlik edecek mesajı içeren bir dize olan isteğe bağlı message alanından oluşur.

Yanıt metni, approvals kaynağının bir örneğini içerir. İleti, bildirim olarak gönderilir ve onay etkinliği günlüğüne de eklenir. İstek gönderen kullanıcının response alanı, ReviewerResponse nesnesinde APPROVED olarak ayarlanır. Ayrıca, bu son gerekli inceleme yanıtıysa onay Status, APPROVED olarak ayarlanır ve tamamlanmış durumda olur.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • APPROVAL_ID: Onayın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.

Mevcut onayları bulma

approvals kaynağı, Drive API'yi kullanarak onaylarınızın durumunu almak ve listelemek için de kullanılabilir.

Bir dosyayla ilgili onayları görüntülemek için dosyanın meta verilerini okuma izniniz olmalıdır. Daha fazla bilgi için Roller ve izinler başlıklı makaleyi inceleyin.

Onay alma

Bir dosyanın onaylanması için get yöntemini approvals kaynağında fileId ve approvalId yol parametreleriyle kullanın. Onay kimliğini bilmiyorsanız list yöntemini kullanarak onayları listeleyebilirsiniz.

Yanıt metni, approvals kaynağının bir örneğini içerir.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • APPROVAL_ID: Onayın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.

Onayları listeleme

Bir dosyayla ilgili onayları listelemek için approvals kaynağında list yöntemini çağırın ve fileId yol parametresini ekleyin.

Yanıt gövdesi, dosyadaki onayların listesinden oluşur. items alanı, formdaki her onay hakkında approvals kaynağı biçiminde bilgiler içerir.

Onayların sayfalandırılmasını özelleştirmek veya onayları filtrelemek için aşağıdaki sorgu parametrelerini de iletebilirsiniz:

  • pageSize: Sayfa başına döndürülecek maksimum onay sayısı. pageSize değerini ayarlamazsanız sunucu en fazla 100 onay döndürür.

  • pageToken: Önceki bir liste çağrısından alınan sayfa jetonu. Bu jeton, sonraki sayfayı almak için kullanılır. Önceki yanıttaki nextPageToken değerine ayarlanmalıdır.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Aşağıdakini değiştirin:

  • FILE_ID: Onayın bulunduğu dosyanın kimliği.
  • ACCESS_TOKEN: Uygulamanızın OAuth 2.0 jetonu.