Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi
API proxy'sine uzantılar eklemek için ExtensionExtension politikasını kullanın.
Uzantı, Apigee Edge'in dışındaki belirli bir kaynağa erişim sağlar. Kaynak, Cloud Storage veya Cloud Speech-to-Text gibi Google Cloud Platform hizmetleri olabilir. Ancak kaynak, HTTP veya HTTPS üzerinden erişilebilen herhangi bir harici kaynak olabilir.
Uzantılara genel bir bakış için Uzantılar nedir? başlıklı makaleyi inceleyin. Giriş niteliğindeki bir eğitim için Eğitim: Uzantı ekleme ve kullanma başlıklı makaleye bakın.
ExtensionDescription politikasından bir uzantıya erişmeden önce uzantıyı Apigee Edge kuruluşunuzda yüklü olan bir uzantı paketinden eklemeniz, yapılandırmanız ve dağıtmanız gerekir.
Sana Özel
Aşağıda Cloud Logging uzantısıyla kullanılacak örnek bir politika gösterilmektedir:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
<DisplayName>Logging Extension</DisplayName>
<Connector>cloud-extension-sample</Connector>
<Action>log</Action>
<Input>{
"logName" : "example-log",
"metadata" : "test-metadata",
"message" : "This is a test"
}</Input>
<Output>cloud-extension-example-log</Output>
</ConnectorCallout>
Cloud Logging uzantısının kullanımıyla ilgili eksiksiz bir eğitim için Eğitim: Uzantıları kullanma bölümüne bakın.
Kullanılabilir tüm uzantılara ilişkin örnekler için Uzantı referansına genel bakış bölümüne bakın.
ExtensionDescription politikası hakkında
API proxy'si içinden harici bir kaynağa erişmek için yapılandırılmış bir uzantı kullanmak istediğinizde ExtensionCallout politikasını kullanın.
Bu politikayı kullanabilmeniz için şunlara ihtiyacınız vardır:
- Bu politikadan erişmek istediğiniz harici kaynakla ilgili birkaç ayrıntı. Bu ayrıntılar kaynağa özgü olacaktır. Örneğin, politika Cloud Firestore veritabanınıza erişecekse oluşturmak veya erişmek istediğiniz koleksiyon ve belge adını bilmeniz gerekir. Bu politikanın istek ve yanıt işlemesini yapılandırırken genellikle kaynağa özgü bilgileri kullanırsınız.
- API proxy'nizin dağıtılacağı ortama bir uzantı eklenir, yapılandırılır ve dağıtılır. Başka bir deyişle, bu politikayı belirli bir Google Cloud hizmetine erişmek için kullanacaksanız ortamınızda bu hizmet için dağıtılmış bir uzantı bulunmalıdır. Yapılandırma ayrıntıları genellikle proje kimliği veya hesap adı gibi kaynağa erişimi daraltmak için gereken bilgileri içerir.
PostClientFlow'da Extension callout politikasını kullanma
ExtensionExtension politikasını bir API proxy'sinin PostClientFlow bölümünden çağırabilirsiniz. PostClientFlow, yanıt istekte bulunan istemciye gönderildikten sonra yürütülerek tüm metriklerin günlük kaydı için kullanılabilir olmasını sağlar. PostClientFlow'u kullanmayla ilgili ayrıntılar için API proxy yapılandırma referansı bölümüne bakın.
Google Cloud Logging uzantısını bir PostClientFlow'dan çağırmak için Extension yönerge politikasını kullanmak isterseniz kuruluşunuzda features.allowExtensionsInPostClientFlow
işaretinin true
olarak ayarlandığından emin olun.
Herkese Açık Bulut İçin Apigee Edge müşterisiyseniz
features.allowExtensionsInPostClientFlow
işareti varsayılan olaraktrue
şeklinde ayarlanır.Private Cloud için Apigee Edge müşterisiyseniz
features.allowExtensionsInPostClientFlow
işaretinitrue
olarak ayarlamak için Güncelleme kuruluş özelliklerini API'yi kullanın.
PostClientFlow'dan MessageLogging politikasının çağrılmasıyla ilgili tüm kısıtlamalar ExtensionExtension politikası için de geçerlidir. Daha fazla bilgi için Kullanım notlarına bakın.
Öğe referansı
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
<DisplayName/>
<Connector/>
<Action/>
<Input/>
<Output/>
</ConnectorCallout>
<Connector callout> özellikleri
<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">
Aşağıdaki tabloda, tüm politika üst öğelerinde ortak olan özellikler açıklanmaktadır:
Özellik | Açıklama | Varsayılan | Varlık |
---|---|---|---|
name |
Politikanın dahili adı. İsteğe bağlı olarak, politikayı yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı bir doğal dil adıyla etiketlemek için |
Yok | Gerekli |
continueOnError |
Bir politika başarısız olduğunda hata döndürülmesi için Bir politika başarısız olduktan sonra bile akış yürütülmesinin devam etmesi için |
false | İsteğe bağlı |
enabled |
Politikayı uygulamak için Politikayı devre dışı bırakmak için |
true | İsteğe bağlı |
async |
Bu özellik kullanımdan kaldırıldı. |
false | Kullanımdan kaldırıldı |
<DisplayName> öğesi
Politikayı, yönetim kullanıcı arayüzü proxy düzenleyicisinde farklı bir doğal dil adıyla etiketlemek için name
özelliğine ek olarak kullanın.
<DisplayName>Policy Display Name</DisplayName>
Varsayılan |
Yok Bu öğeyi çıkarırsanız politikanın |
---|---|
Varlık | İsteğe bağlı |
Tür | Dize |
<Action> öğesi
Politikanın çağırması gereken, uzantıya maruz kalan işlem.
<Action>action-exposed-by-extension</Action>
Varsayılan | Yok |
---|---|
Varlık | Gerekli |
Tür | Dize |
Her uzantı, uzantının temsil ettiği kaynağın işlevlerine erişim sağlayan kendi işlem grubunu sunar. Bir işlemi, işlevin bağımsız değişkenlerini belirtmek için <Input>
öğesinin içeriğini kullanarak bu politikayla çağırdığınız bir işlev olarak düşünebilirsiniz. İşlemin yanıtı, <Output>
öğesiyle belirttiğiniz değişkende depolanır.
Uzantının işlevlerinin listesi için bu politikadan çağırdığınız uzantıya ilişkin referansı inceleyin.
<Connector> öğesi
Kullanılacak yapılandırılmış uzantının adı. Bu, bir ortama dağıtım için yapılandırıldığında uzantıya verilen ortam kapsamlı addır.
<Connector>name-of-configured-extension</Connector>
Varsayılan | Yok |
---|---|
Varlık | Gerekli |
Tür | Dize |
Bir uzantının, aynı uzantı paketine dayalı olarak dağıtılan başka bir uzantıdan farklı yapılandırma değerleri olabilir. Bu yapılandırma değerleri, aynı paketten yapılandırılan uzantılar arasındaki çalışma zamanı işlevi açısından önemli farklılıkları gösterebilir. Bu nedenle, çağrılacak doğru uzantıyı belirttiğinizden emin olun.
<Input> öğesi
Uzantıya gönderilecek istek gövdesini içeren JSON.
<Input><![CDATA[ JSON-containing-input-values ]]></Input>
Varsayılan | Yok |
---|---|
Varlık | Uzantıya bağlı olarak isteğe bağlıdır veya zorunludur. |
Tür | Dize |
Bu aslında <Action>
öğesiyle belirttiğiniz işlemin bağımsız değişkenidir. <Input>
öğesinin değeri, çağrıda bulunduğunuz uzantıya ve işleme göre değişir. Her işlemin özellikleriyle ilgili ayrıntılar için uzantı paketi dokümanlarına bakın.
Birçok <Input>
öğe değeri <![CDATA[]]>
bölümü olarak eklenmeden doğru şekilde çalışsa da JSON kurallarının, XML olarak ayrıştırılmayacak değerlere izin verdiğini unutmayın. En iyi uygulama olarak, çalışma zamanı ayrıştırma hatalarını önlemek için JSON'u bir CDATA
bölümü içine alın.
<Input>
öğesinin değeri, özellikleri çağrılacak uzantı işlemine gönderilecek değerleri belirten iyi biçimlendirilmiş JSON'dir. Örneğin, Google Cloud Logging Uzantısı uzantısının log
işlemi; yazılacak günlüğü (logName
), girişe eklenecek meta verileri (metadata
) ve günlük mesajını (data
) belirten değerleri alır.
Örnek:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {
"resource": {
"type": "global",
"labels": {
"project_id": "my-test"
}
}
},
"message" : "This is a test"
}]]></Input>
<Input>
JSON dosyasında akış değişkenlerini kullanma
<Input>
içeriği bir mesaj şablonu olarak kabul edilir. Bu, çalışma zamanında küme parantezleri içine sarmalanmış değişken adının başvuruda bulunulan değişkenin değeriyle değiştirileceği anlamına gelir.
Örneğin, API proxy'sini çağıran istemcinin IP adresini almak amacıyla client.ip
akış değişkenini kullanmak için önceki <Input>
blokunu yeniden yazabilirsiniz:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {
"resource": {
"type": "global",
"labels": {
"project_id": "my-test"
}
}
},
"message" : "{client.ip}"
}]]></Input>
JSON'daki bir özellik değerinin çalışma zamanında tırnak içine alınmasını istiyorsanız JSON kodunuzda tırnak işaretleri kullandığınızdan emin olun. Bu, çalışma zamanında çözümlenecek bir JSON mülk değeri olarak bir akış değişkeni belirttiğinizde bile geçerlidir.
Aşağıdaki <Input>
örneği, iki akış değişkeni referansı içerir:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {my.log.entry.metadata},
"message" : "{client.ip}"
}]]></Input>
Çalışma zamanında, JSON özellik değerleri aşağıdaki gibi çözümlenir:
logName
özellik değeri -- dize değişmez değeriexample-log
.metadata
özellik değeri -- tırnak işaretleri arasında olmadanmy.log.entry.metadata
akış değişkeni değeridir. Bu değişken, değişkenin değerinin bir nesneyi temsil eden JSON değeri olması durumunda yararlı olabilir.message
özellik değeri -- tırnak işaretleri arasında olanclient.ip
akış değişkeni değeri.
<Çıkış> öğesi
Uzantı işleminin yanıtını depolayan bir değişkenin adı.
<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->
veya
<Output parsed="false">variable-name</Output> <!-- The JSON object inside the variable is raw, unparsed -->
Varsayılan | Yok |
---|---|
Varlık | Uzantıya bağlı olarak isteğe bağlıdır veya zorunludur. |
Tür | parsed özellik ayarına bağlı olarak ayrıştırılmış nesne veya Dize. |
Yanıt alındığında, yanıt değeri burada belirttiğiniz değişkene yerleştirilir. Başka API proxy kodundan bu değişkene erişebilirsiniz.
Uzantı yanıt nesneleri JSON biçimindedir. Politikanın JSON dosyasını nasıl ele alacağına ilişkin iki seçenek vardır:
- Ayrıştırılmış (varsayılan): Politika, JSON nesnesini ayrıştırır ve JSON verileriyle otomatik olarak değişkenler oluşturur. Örneğin, JSON dosyasında
"messageId" : 12345;
bulunuyorsa ve çıkış değişkeniniziextensionOutput
olarak adlandırırsanız bu ileti kimliğine, diğer politikalarda{extensionOutput.messageId}
değişkenini kullanarak erişebilirsiniz. - Ayrıştırılmamış: Çıkış değişkeni, uzantıdan gelen ham ve ayrıştırılmamış JSON yanıtını içerir. (İsterseniz yanıt değerini JavaScript politikasını kullanarak ayrı bir adımda ayrıştırabilirsiniz.)
<Exit> Özellikleri
Özellik | Açıklama | Varsayılan | Varlık |
---|---|---|---|
ayrıştırılmış | Uzantıdan döndürülen JSON nesnesini ayrıştırır. Böylece, JSON nesnesindeki verilere diğer politikalar tarafından değişken olarak erişilebilir. | true | İsteğe bağlı |
Akış değişkenleri
Yok.
Hata kodları
Apigee Edge politikalarından döndürülen hatalar, Politika hatası referansı bölümünde açıklanan tutarlı bir biçimdedir.
Bu bölümde, bu politika bir hata tetiklediğinde ayarlanan hata mesajları ve akış değişkenleri açıklanmaktadır. Bu bilgiler, bir proxy için hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme konularına göz atın.
Çalışma zamanı hataları
Bu hatalar, politika yürütüldüğünde ortaya çıkabilir.
Hata adı | HTTP durumu | Neden |
---|---|---|
Yürütme Başarısız | 500 |
Uzantı bir hata mesajıyla yanıt verir. |
Dağıtım hataları
Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda oluşabilir.
Hata adı | Şu durumda gerçekleşir: | Düzelt |
---|---|---|
InvalidConnectorInstance |
<Connector> öğesi boş. |
build |
ConnectorInstanceDoesNotExists |
<Connector> öğesinde belirtilen Uzantı ortamda mevcut değil. |
build |
InvalidAction |
ExtensionCallout politikasındaki <Action> öğesi eksik veya boş bir değere ayarlanmış. |
build |
AllowExtensionsInPostClientFlow |
PostClient Stream'de ExtensionCallout politikası bulunması yasaktır. | build |