Azure İşlevi /REST API denetimlerini çağırma

Azure İşlevini Çağır / REST API Denetimleri, belirli bir işlem hattı aşamasının korumalı bir kaynağa erişmesine izin verilip verilmediğine karar vermek için kod yazmanızı sağlar. Bu denetimler iki modda çalıştırılabilir:

• Zaman Uyumsuz (Önerilen): Azure DevOps'un Azure İşlevi/REST API uygulamasının aşamalı erişim kararıyla Azure DevOps'a geri çağrılmaya hazır olduğu gönderim modu
• Zaman uyumlu: Azure DevOps'un aşamalı erişim kararı almak için Azure İşlevi/REST API'sini düzenli aralıklarla çağırdığı yoklama modu

Bu kılavuzun geri kalanında Azure İşlevi / REST API Denetimleri'ne yalnızca denetimler olarak başvuracağız.

Denetimleri kullanmanın önerilen yolu zaman uyumsuz moddadır. Bu mod size denetim mantığı üzerinde en yüksek düzeyde denetim sunar, sistemin hangi durumda olduğunu anlamanızı kolaylaştırır ve Azure Pipelines'ı denetim uygulamanızdan ayrıştırarak en iyi ölçeklenebilirliği sağlar. Tüm zaman uyumlu denetimler zaman uyumsuz denetimler modu kullanılarak uygulanabilir.

Zaman uyumsuz denetimler

Zaman uyumsuz modda Azure DevOps, Azure İşlevi /REST API denetimine bir çağrı yapar ve kaynak erişim kararıyla bir geri çağırma bekler. Bekleme süresi boyunca Azure DevOps ile denetim uygulamanız arasında açık HTTP bağlantısı yoktur.

Bu bölümün geri kalanında Azure İşlevi denetimleri anlatılır, ancak aksi belirtilmedikçe, bu kılavuz REST API denetimlerini çağırma için de geçerlidir.

Zaman uyumsuz denetimlerin uygulanması önerilir

Önerilen zaman uyumsuz modda iki iletişim adımı vardır:

1. Çek yükünü teslim edin. Azure Pipelines, yalnızca çek yükünü teslim etmek ve yerinde bir karar almamak için Azure İşlevinize /REST API'nize bir HTTP çağrısı yapar. İşleviniz yalnızca bilgilerin alınıp alınıp Azure DevOps ile HTTP bağlantısını sonlandırmalıdır. Denetim uygulamanızın HTTP isteğini 3 saniye içinde işlemesi gerekir.
2. Geri arama yoluyla erişim kararı verme. Denetiminiz zaman uyumsuz olarak çalışmalı, işlem hattının korumalı kaynağa erişmesi için gerekli koşulu değerlendirmelidir (muhtemelen zaman içinde farklı noktalarda birden çok değerlendirme yapmalıdır). Son bir karara ulaştığında, Azure İşleviniz kararı iletmek için Azure DevOps'a bir HTTP REST çağrısı yapar. Herhangi bir zamanda, Azure DevOps ile denetim uygulamanız arasında tek bir açık HTTP bağlantısı olmalıdır. Bunu yaptığınızda hem Azure İşlevi tarafınızda hem de Azure Pipelines tarafında kaynaklar kaydedilir.

Bir denetim başarılı olursa işlem hattının korumalı bir kaynağa erişimine izin verilir ve dağıtım aşaması devam edebilir. Bir denetim başarısız olursa aşama başarısız olur. Tek bir aşamada birden çok denetim varsa, korumalı kaynaklara erişime izin verilmeden önce tümünün geçirilmesi gerekir, ancak aşamayı başarısız yapmak için tek bir hata yeterlidir.

Tek bir Azure İşlevi denetimi için zaman uyumsuz modun önerilen uygulaması aşağıdaki diyagramda gösterilmiştir.

Diyagramdaki adımlar şunlardır:

1. Teslimi Denetleyin. Azure Pipelines, işlem hattı aşaması dağıtmaya hazırlanır ve korumalı bir kaynağa erişim gerektirir. İlgili Azure İşlevi denetimini çağırır ve http 200 durum koduyla biten çağrıyla alındı onayı bekler. Aşama dağıtımı bir karar bekleniyorken duraklatıldı.
2. Değerlendirme'ye bakın. Bu adım, kendi Azure kaynaklarınızda çalışan ve kodu tamamen sizin denetiminizde olan Azure İşlevi uygulamanızın içinde gerçekleşir. Azure İşlevinizin şu adımları izlemesini öneririz:
   • 2.1 Zaman uyumsuz bir görev başlatma ve HTTP durum kodunu döndürme200
   • 2.2 Birden çok koşul değerlendirmesi gerçekleştirebileceği bir iç döngü girin
   • 2.3 Erişim koşullarını değerlendirme
   • 2.4 Son bir karara ulaşamazsa, sonraki bir nokta için koşulların yeniden değerlendirilmesini yeniden zamanlayın, ardından 2.3. adıma gidin
3. Karar İletişimi. Azure işlevi, erişim kararıyla Azure Pipelines'a geri çağrır. Aşama dağıtımı devam edebilir

Zaman uyumsuz denetimler için önerilen yapılandırma

Azure İşlevi / REST API yapılandırmayı denetleme panelinde şunları yaptığınızdan emin olun:

• Tamamlama olayı için Seçili Geri Arama
• Değerlendirmeler arasındaki süreyi (dakika) 0 olarak ayarlayın

Değerlendirmeler arasındaki süreyi sıfır olmayan bir değere ayarlamak, denetim kararının (başarılı/başarısız) nihai olmadığı anlamına gelir. Diğer tüm Onaylar ve Denetimler son duruma gelene kadar denetim yeniden değerlendirilir.

İşlem hattı çalıştırma bilgilerini denetimlere geçirme

Denetimi yapılandırırken, denetiminize göndermek istediğiniz işlem hattı çalıştırma bilgilerini belirtebilirsiniz. En azından şunları göndermeniz gerekir:

• "PlanUrl": "$(system.CollectionUri)"
• "ProjectId": "$(system.TeamProjectId)"
• "HubName": "$(system.HostType)"
• "PlanId": "$(system.PlanId)"
• "JobId": "$(system.JobId)"
• "TaskInstanceId": "$(system.TaskInstanceId)"
• "AuthToken": "$(system.AccessToken)"

Bu anahtar-değer çiftleri, Azure Pipelines tarafından yapılan REST çağrısında varsayılan olarak Headers ayarlanır.

Azure DevOps'a çağrı yapmak için kullanmanız AuthToken gerekir( örneğin, denetiminiz bir kararla geri ararken).

Azure DevOps'a çağrı

Bir karara varmak için, denetiminizin geçerli işlem hattı çalıştırması hakkında denetime geçirilmeyecek bilgilere ihtiyacı olabilir, bu nedenle denetimin bunu alması gerekir. Denetiminizin, bir işlem hattı çalıştırmasını belirli bir görevi( örneğin statik analiz görevi) yürüttüğünüzü doğruladığını düşünün. Denetiminizin Azure DevOps'a çağrı yapması ve zaten yürütülen görevlerin listesini alması gerekir.

Azure DevOps'a çağrı yapmak için, kişisel erişim belirteci (PAT) yerine denetim yürütmesi için verilen iş erişim belirtecini kullanmanızı öneririz. Belirteç, varsayılan olarak üst bilgide AuthToken denetimlerinize zaten sağlanmıştır.

PAT'lerle karşılaştırıldığında, iş erişim belirteci azaltmaya daha az eğilimlidir, el ile yenilemeye gerek yoktur ve kişisel bir hesaba bağlı değildir. Belirteç 48 saat geçerlidir.

İş erişim belirtecinin kullanılması, Azure DevOps REST API azaltma sorunlarını ortadan kaldırır. PAT kullandığınızda, işlem hattınızın tüm çalıştırmaları için aynı PAT'yi kullanırsınız. Çok sayıda işlem hattı çalıştırırsanız PAT kısıtlanır. Bu, her denetim yürütmesi için yeni bir belirteç oluşturulduğundan iş erişim belirteci ile ilgili bir sorun değildir.

Belirteç, fabrikamFiberChat derleme hizmeti (FabrikamFiber) gibi bir işlem hattını çalıştırmak için kullanılan derleme kimliği için verilir. Başka bir deyişle belirteç, konak işlem hattının erişebildiği depolara veya işlem hattı çalıştırmalarına erişmek için kullanılabilir. YAML işlem hatlarındaki depolara erişimi korumayı etkinleştirdiyseniz kapsamı yalnızca işlem hattı çalıştırmasında başvuruda bulunan depolarla daha da kısıtlanır.

Denetiminizin İşlem Hattıyla ilgili olmayan kaynaklara (örneğin, Boards kullanıcı hikayeleri) erişmesi gerekiyorsa, işlem hatlarının derleme kimliklerine bu tür izinler vermelisiniz. Denetiminiz birden çok projeden tetiklenebiliyorsa, tüm projelerdeki tüm işlem hatlarının gerekli kaynaklara erişebildiğinden emin olun.

Kararı Azure DevOps'a geri gönderme

Denetim uygulamanızın, Azure Pipelines'a geri bir karar iletmek için Olay Sonrası REST API çağrısı kullanması gerekir. Aşağıdaki özellikleri belirttiğinizden emin olun:

• Headers: Bearer {AuthToken}
• Body:

{
    "name": "TaskCompleted",
    "taskId": "{TaskInstanceId}",
    "jobId": "{JobId}",
    "result": "succeeded|failed"
}

Denetimlerden Azure DevOps'a durum güncelleştirmeleri gönderme

Azure Pipelines REST API'lerini kullanarak denetimlerinizin içinden Azure Pipelines kullanıcılarına durum güncelleştirmeleri sağlayabilirsiniz. Bu işlev, örneğin kullanıcılara denetimin bir dış eylem beklediğini bildirmek istiyorsanız (örneğin, birinin ServiceNow biletini onaylaması gerekir) kullanışlıdır.

Durum güncelleştirmelerini gönderme adımları şunlardır:

1. Görev günlüğü oluşturma
2. Görev günlüğüne ekleme
3. Zaman çizelgesi kaydını güncelleştirme

Tüm REST API çağrılarının kimliğinin doğrulanması gerekir.

Örnekler

Temel Azure İşlevi denetimi

Bu temel örnekte Azure İşlevi, çağırma işlem hattı çalıştırmasının korumalı bir kaynağa erişim izni vermeden önce bir CmdLine görevi yürütdüğünü denetler.

Azure İşlevi aşağıdaki adımları izler:

1. Çek yükünün alındını onaylar
2. Denetimin başlatıldığını Azure Pipelines'a bir durum güncelleştirmesi gönderir
3. İşlem hattı çalıştırmasının Zaman Çizelgesi girdisini almak için Azure Pipelines'a geri çağırma yapmak için kullanılır {AuthToken}
4. Zaman Çizelgesi'nin ile bir görev (görevin "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" kimliği CmdLine ) içerip içermediğini denetler
5. Aramanın sonucuyla bir durum güncelleştirmesi gönderir
6. Azure Pipelines'a denetim kararı gönderir

Bu örneği GitHub'dan indirebilirsiniz.

Bu Azure İşlevi denetimini kullanmak için denetimi yapılandırırken aşağıdakileri Headers belirtmeniz gerekir:

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

Gelişmiş Azure İşlevi denetimi

Bu gelişmiş örnekte Azure İşlevi, işlem hattı çalıştırmasını tetikleyen işleme iletisinde başvuruda bulunan Azure Boards iş öğesinin doğru durumda olup olmadığını denetler.

Azure İşlevi aşağıdaki adımları izler:

1. Çek yükünün alındını onaylar
2. Denetimin başlatıldığını Azure Pipelines'a bir durum güncelleştirmesi gönderir
3. İşlem hattı çalıştırmasını tetikleyen işleme iletisinde başvuruda bulunılan Azure Boards iş öğesinin durumunu almak için Azure Pipelines'a geri çağırma yapmak için kullanır {AuthToken}
4. İş öğesinin Completed durumunda olup olmadığını denetler
5. Denetimin sonucuyla bir durum güncelleştirmesi gönderir
6. İş öğesi Completed durumunda değilse, 1 dakika içinde başka bir değerlendirmeyi yeniden zamanlar
7. İş öğesi doğru duruma geldiğinde Azure Pipelines'a olumlu bir karar gönderir

Bu örneği GitHub'dan indirebilirsiniz.

Bu Azure İşlevi denetimini kullanmak için denetimi yapılandırırken aşağıdakileri Headers belirtmeniz gerekir:

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

Hata işleme

Şu anda Azure Pipelines tek bir denetim örneğini en fazla 2.000 kez değerlendirir.

Denetiminiz yapılandırılan zaman aşımı içinde Azure Pipelines'a geri çağrılmazsa, ilişkili aşama atlanır. Buna bağlı aşamalar da atlanır.

Zaman uyumlu denetimler

Zaman uyumlu modda Azure DevOps, korumalı bir kaynağa erişime izin verilip verilmeyeceği konusunda anında karar almak için Azure İşlevi /REST API denetimi çağrısı yapar.

Tek bir Azure İşlevi denetimi için eşitleme modunun uygulanması aşağıdaki diyagramda gösterilmiştir.

Adımlar şunlardır:

1. Azure Pipelines, işlem hattı aşaması dağıtmaya hazırlanır ve korumalı bir kaynağa erişim gerektirir
2. Aşağıdakilerin yer aldığı bir iç döngü girer:

• 2.1. Azure Pipelines ilgili Azure İşlevi denetimini çağırır ve bir karar bekler
• 2.2. Azure İşleviniz erişime izin vermek için gereken koşulları değerlendirir ve bir karar döndürür
• 2.3. Azure İşlevi yanıt gövdesi tanımladığınız Başarı ölçütlerini karşılamıyorsa ve Değerlendirmeler arasındaki süre sıfır değilse, Azure Pipelines değerlendirmeler arasında zaman geçtikten sonra başka bir denetim değerlendirmesini yeniden zamanlar

Zaman uyumlu denetimleri yapılandırma

Azure İşlevi / REST API'sinin zaman uyumlu modunu kullanmak için yapılandırmayı denetleme panelinde şunları yaptığınızdan emin olun:

• Gelişmiş altındaki Tamamlama olayı için Seçilen ApiResponse
• Denetimin yanıt gövdesine göre denetimin ne zaman geçirildiğini tanımlayan Başarı ölçütü belirtildi
• Denetim seçenekleri altında değerlendirmeler arasındaki süreyi 0 olarak ayarlayın
• Zaman Aşımı'na bir denetimin başarılı olmasını ne kadar süreyle beklemek istediğinizi ayarlayın. Olumlu bir karar yoksa ve Zaman aşımına ulaşılırsa ilgili işlem hattı aşaması atlanır

Değerlendirmeler arasındaki süre ayarı, denetimin kararının ne kadar süre geçerli olduğunu tanımlar. 0 değeri, kararın nihai olduğu anlamına gelir. Sıfır olmayan bir değer, denetimin yapılandırılan aralık sonrasında, kararı negatif olduğunda yeniden deneneceği anlamına gelir. Birden çok Onay ve Denetim çalıştırıldığında, karardan bağımsız olarak denetim yeniden deneniyor.

Değerlendirme sayısı üst sınırı, Zaman Aşımı ile Zaman arasındaki değerlendirme değerleri arasındaki oran ile tanımlanır. Bu oranın en fazla 10 olduğundan emin olmanız önerilir.

İşlem hattı çalıştırma bilgilerini denetimlere geçirme

Denetimi yapılandırırken, Azure İşlevinize /REST API denetiminize göndermek istediğiniz işlem hattı çalıştırma bilgilerini belirtebilirsiniz. Varsayılan olarak, Azure Pipeline yaptığı HTTP çağrısına Headers aşağıdaki bilgileri ekler.

• "PlanUrl": "$(system.CollectionUri)"
• "ProjectId": "$(system.TeamProjectId)"
• "HubName": "$(system.HostType)"
• "PlanId": "$(system.PlanId)"
• "JobId": "$(system.JobId)"
• "TaskInstanceId": "$(system.TaskInstanceId)"
• "AuthToken": "$(system.AccessToken)"

Büyük olasılıkla denetiminizin 3 saniyeden uzun sürmesine neden olacağı için denetimin başarısız olması nedeniyle Azure DevOps'a zaman uyumlu modda çağrı yapmanızı önermeyiz.

Hata işleme

Şu anda Azure Pipelines tek bir denetim örneğini en fazla 2.000 kez değerlendirir.

Zaman uyumsuz ve zaman uyumlu denetimler ne zaman kullanılır?

Bazı örnek kullanım örneklerine ve kullanılması önerilen denetim türüne göz atalım.

Dış bilgiler doğru olmalıdır

Bir üretim kaynağına Hizmet Bağlantınız olduğunu ve yalnızca ServiceNow biletindeki bilgilerin doğru olması durumunda erişime izin verildiğinden emin olmak istediğinizi varsayalım. Bu durumda akış aşağıdaki gibi olacaktır:

• ServiceNow biletinin doğruluğunu doğrulayan zaman uyumsuz bir Azure İşlevi denetimi eklersiniz
• Hizmet Bağlantısı'nı kullanmak isteyen bir işlem hattı çalıştığında:
  • Azure Pipelines check işlevinizi çağırır
  • Bilgiler yanlışsa, denetim olumsuz bir karar döndürür. Bu sonucu varsay
  • İşlem hattı aşaması başarısız oluyor
  • ServiceNow biletindeki bilgileri güncelleştirirsiniz
  • Başarısız olan aşamayı yeniden başlatabilirsiniz
  • Denetim yeniden çalıştırılır ve bu kez başarılı olur
  • İşlem hattı çalıştırması devam ediyor

Dış onay verilmelidir

Bir üretim kaynağına Hizmet Bağlantınız olduğunu ve erişime izin verildiğinden emin olmak istediğinizi ancak yönetici bir ServiceNow biletini onayladıktan sonra yapmak istediğinizi varsayalım. Bu durumda akış aşağıdaki gibi olacaktır:

• ServiceNow biletinin onaylandığını doğrulayan zaman uyumsuz bir Azure İşlevi denetimi eklersiniz
• Hizmet Bağlantısı'nı kullanmak isteyen bir işlem hattı çalıştığında:
  • Azure Pipelines, check işlevinizi çağırır.
  • ServiceNow bileti onaylanmamışsa, Azure İşlevi Azure Pipelines'a bir güncelleştirme gönderir ve biletin durumunu 15 dakika içinde denetlemek için kendisini yeniden zamanlar
  • Bilet onaylandıktan sonra, denetim olumlu bir kararla Azure Pipelines'a geri döner
  • İşlem hattı çalıştırması devam ediyor

Geliştirme süreci izlendi

Üretim kaynağına Hizmet Bağlantınız olduğunu ve yalnızca kod kapsamının %80'in üzerinde olması durumunda erişime izin verildiğinden emin olmak istediğinizi varsayalım. Bu durumda akış aşağıdaki gibi olacaktır:

• İşlem hattınızı, aşama hataları derlemenin başarısız olmasına neden olacak şekilde yazarsınız
• İlişkili işlem hattı çalıştırması için kod kapsamını doğrulayan zaman uyumsuz bir Azure İşlevi denetimi eklersiniz
• Hizmet Bağlantısı'nı kullanmak isteyen bir işlem hattı çalıştığında:
  • Azure Pipelines check işlevinizi çağırır
  • Kod kapsamı koşulu karşılanmazsa, denetim negatif bir karar döndürür. Bu sonucu varsay
  • Denetim hatası aşamanızın başarısız olmasına neden olur ve bu da işlem hattı çalıştırmanızın başarısız olmasına neden olur
• Mühendislik ekibi% 80 kod kapsamına ulaşmak için gerekli birim testlerini ekler
• Yeni bir işlem hattı çalıştırması tetiklendiğinde bu kez denetim başarılı olur
  • İşlem hattı çalıştırması devam ediyor

Performans ölçütleri karşılanmalıdır

Bir kanarya dağıtımıyla başlayarak sisteminizin yeni sürümlerini birden çok adımda dağıttığınızı varsayalım. Kanarya dağıtımınızın performansının yeterli olduğundan emin olmak istiyorsunuz. Bu durumda akış aşağıdaki gibi olacaktır:

• Zaman uyumsuz bir Azure İşlevi denetimi eklersiniz
• Hizmet Bağlantısı'nı kullanmak isteyen bir işlem hattı çalıştığında:
  • Azure Pipelines check işlevinizi çağırır
  • Denetim, kanarya dağıtımının performansının bir izleyicisini başlatır
  • Denetim, performansın nasıl geliştiğini görmek için birden çok değerlendirme denetim noktası zamanlar
  • Kanarya dağıtımının performansına yeterince güvendiğinizde, Azure İşleviniz olumlu bir kararla Azure Pipelines'a geri döner
  • İşlem hattı çalıştırması devam ediyor

Dağıtım nedeni geçerli olmalıdır

Bir üretim ortamı kaynağına Hizmet Bağlantınız olduğunu ve bu kaynağa erişimin yalnızca el ile kuyruğa alınmış derlemeler için gerçekleşmesini istediğinizi varsayalım. Bu durumda akış aşağıdaki gibi olacaktır:

• İşlem hattı çalıştırması için şunu doğrulayan Build.Reason zaman uyumlu bir Azure İşlevi denetimi eklersiniz:Manual
• Azure İşlevi denetimini Build.Reason , Headers
• Değerlendirmeler arasındaki süre değerini 0 olarak ayarlarsınız, bu nedenle hata veya geçiş sondur ve yeniden değerlendirme gerekmez
• Hizmet Bağlantısı'nı kullanmak isteyen bir işlem hattı çalıştığında:
  • Azure Pipelines check işlevinizi çağırır
  • Nedeni dışındaysa Manual, denetim başarısız olur ve işlem hattı çalıştırması başarısız olur

Birden çok denetim

Azure Pipelines işlem hattı çalıştırmasında bir aşama dağıtmadan önce birden çok denetimin geçmesi gerekebilir. Korumalı bir kaynakla ilişkilendirilmiş bir veya daha fazla Denetim olabilir. Bir aşama birden çok korumalı kaynak kullanabilir. Azure Pipelines, bir aşamada kullanılan her korumalı kaynakla ilişkili tüm denetimleri toplar ve bunları eşzamanlı olarak değerlendirir.

İşlem hattı çalıştırmasının yalnızca tüm denetimler aynı anda geçtiğinde bir aşamaya dağıtılmasına izin verilir. Tek bir son olumsuz karar, işlem hattının erişiminin reddedilmesine ve aşamanın başarısız olmasına neden olur.

Denetimleri önerilen şekilde kullandığınızda (zaman uyumsuz, son durumlarla), erişim kararlarını son haline getirir ve sistemin durumunu anlamayı kolaylaştırır.

Örnekler için Birden Çok Onay ve Denetimler bölümüne göz atın.

Daha fazla bilgi edinin

• Onaylar ve Denetimler
• Azure İşlev Görevi Çağırma
• REST API Görevini Çağırma