Zasady dotyczące objaśnień w rozszerzeniach

Przeglądasz dokumentację Apigee Edge.
Przejdź do Dokumentacja Apigee X. informacje.

Użyj zasady ExtensionCallout, aby dodać rozszerzenie do serwera proxy interfejsu API.

Rozszerzenie zapewnia dostęp do określonego zasobu spoza Apigee Edge. Zasóbem mogą być usługi Google Cloud Platform, takie jak Cloud Storage lub Cloud Speech-to-Text. Może to być dowolny zasób zewnętrzny dostępny przez HTTP lub HTTPS.

Ogólne informacje o rozszerzeniach znajdziesz w artykule Czym są rozszerzenia? Aby zapoznać się z samouczkiem wprowadzającym, przeczytaj Samouczek: dodawanie rozszerzeń i korzystanie z nich.

Zanim uzyskasz dostęp do rozszerzenia z zasady ExtensionCallout, musisz dodać, skonfigurować i wdrożyć rozszerzenie z pakietu rozszerzeń, który jest już zainstalowany w organizacji Apigee Edge.

Przykłady

Poniżej znajduje się przykładowa zasada, której można użyć z rozszerzeniem Cloud Logging:

<?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>

Zobacz Samouczek: używanie rozszerzeń w przypadku pełny samouczek, korzystając z rozszerzenia Cloud Logging.

Przykłady wszystkich dostępnych rozszerzeń znajdziesz w artykule Omówienie rozszerzeń.

Informacje o zasadach ExtensionCallout

Użyj zasady ExtensionCallout, gdy chcesz używać skonfigurowanego rozszerzenia do uzyskiwania dostępu do zasobu zewnętrznego za pomocą serwera proxy interfejsu API.

Aby korzystać z tej zasady, musisz:

• Kilka informacji o zasobie zewnętrznym, do którego chcesz mieć dostęp z tej zasady. Dane te będą powiązane z konkretnym zasobem. Jeśli na przykład zasada będzie miała dostęp do bazy danych Cloud Firestore, musisz znać nazwę kolekcji i dokumentu, do którego chcesz utworzyć lub uzyskać dostęp. Do konfigurowania obsługi żądań i odpowiedzi w tej zasadzie zwykle używasz informacji o zasobach.
• dodanie, skonfigurowanie i wdrożenie rozszerzenia; w środowisku, w którym zostanie wdrożony serwer proxy interfejsu API. Innymi słowy, jeśli zamierzasz użyć tej zasady, aby uzyskać dostęp do konkretnej usługi Google Cloud, to w środowisku musi istnieć rozszerzenie wdrożone dla tej usługi. Szczegóły konfiguracji zawierają zwykle informacje wymagane do zawężania zakresu. dostęp do zasobu, np. identyfikator projektu lub nazwę konta.

Używanie zasady ExtensionCallout w PostClientFlow

Zasadę ExtensionCallout możesz wywołać z poziomu PostClientFlow serwera proxy interfejsu API. Działanie PostClientFlow jest wykonywane po wysłaniu odpowiedzi do klienta, który wysłał żądanie. co daje pewność, że wszystkie wskaźniki są dostępne na potrzeby logowania. Szczegółowe informacje o korzystaniu z PostClientFlow znajdziesz w dokumentacji konfiguracji serwera proxy interfejsu API.

Jeśli chcesz używać zasady ExtensionCallout do wywoływania rozszerzenia Google Cloud Logging z PostClientFlow, sprawdź, czy flaga features.allowExtensionsInPostClientFlow jest ustawiona na true w Twojej organizacji.

• Jeśli korzystasz z Apigee Edge dla Public Cloud, Flaga features.allowExtensionsInPostClientFlow jest domyślnie ustawiona na true.

• Jeśli jesteś klientem Apigee Edge dla Private Cloud, użyj Interfejs API aktualizacji właściwości organizacji ustaw flagę features.allowExtensionsInPostClientFlow na true.

Wszystkie ograniczenia wywoływania zasad MessageLogging z PostClientFlow mają zastosowanie również do zasad ExtensionCallout. Więcej informacji znajdziesz w sekcji Uwagi o użytkowaniu.

Odwołanie do elementu

<?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>

<ConnectorCallout> atrybuty

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

<DisplayName> element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

<Action> element

Działanie ujawnione przez rozszerzenie, które ma wywołać zasada.

<Action>action-exposed-by-extension</Action>

Każde rozszerzenie ujawnia własny zestaw działań zapewniających dostęp do funkcji zasobu reprezentowanego przez to rozszerzenie. Działanie można sobie wyobrazić jako funkcję, którą wywołujesz za pomocą tej zasady, używając zawartości elementu <Input> do określenia argumentów funkcji. Odpowiedź działania jest przechowywana w zmiennej określonej w elemencie <Output>.

Listę funkcji rozszerzenia znajdziesz w dokumentacji rozszerzenia, które wywołujesz na podstawie tej zasady.

<Łącznik> element

Nazwa skonfigurowanego rozszerzenia, które ma być używane. Jest to nazwa ograniczona do środowiska nadana rozszerzeniu, gdy zostało skonfigurowane do wdrożenia w środowisku.

<Connector>name-of-configured-extension</Connector>

Rozszerzenie ma wartości konfiguracyjne, które mogą się różnić od wartości innego wdrożonego rozszerzenia na podstawie tego samego pakietu rozszerzeń. Te wartości konfiguracyjne mogą reprezentować istotne różnice w funkcjach środowiska wykonawczego między rozszerzeniami konfigurowanymi z tego samego pakietu, dlatego musisz wybrać odpowiednie rozszerzenie do wywołania.

&lt;Input&gt; element

Plik JSON zawierający treść żądania, która ma zostać wysłana do rozszerzenia.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Jest to argument związany z działaniem, które określasz w elemencie <Action>. Wartość elementu <Input> będzie się różnić w zależności od rozszerzenia i wywołanego działania. Szczegółowe informacje o właściwościach poszczególnych działań znajdziesz w dokumentacji pakietów rozszerzeń.

Pamiętaj, że chociaż wiele wartości elementów <Input> będzie działać prawidłowo bez uwzględnienia sekcji <![CDATA[]]>, reguły JSON zezwalają na wartości, które nie są analizowane jako XML. Aby uniknąć błędów analizy w czasie działania, umieść plik JSON w sekcji CDATA.

Wartością elementu <Input> jest prawidłowy format JSON, którego właściwości określają wartości który ma być wysyłany do działania rozszerzenia, które ma je wywołać. Na przykład parametr Rozszerzenie Google Cloud Logging działanie log rozszerzenia przyjmuje wartości określające dziennik do zapisu (logName), metadanych, które mają zostać dołączone do wpisu (metadata) i komunikatu logu (data). Oto przykład:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Używanie zmiennych przepływu w pliku JSON <Input>

Zawartość pliku <Input> jest traktowana jako szablon wiadomości. Oznacza to, że nazwa zmiennej w nawiasach klamrowych jest zastępowana w czasie działania wartością zmiennej, do której prowadzi wskazana wartość.

Możesz na przykład przepisać poprzedni blok <Input>, aby użyć zmiennej przepływu client.ip do uzyskania adresu IP klienta wywołującego serwer proxy interfejsu API:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

Jeśli chcesz, aby wartość właściwości w pliku JSON była umieszczana w cudzysłowach na czas działania, użyj cudzysłowów w kodzie JSON. Dzieje się tak nawet wtedy, gdy określisz zmienną przepływu jako wartość właściwości JSON, która ma być rozpoznawana w czasie działania.

Poniższy przykładowy zasób (<Input>) zawiera 2 odwołania do zmiennych przepływu:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

W czasie działania wartości właściwości JSON będą wyglądać w ten sposób:

• Wartość właściwości logName -- literał ciągu znaków example-log.
• metadata – wartość zmiennej przepływu my.log.entry.metadata bez cudzysłowów. Może to być przydatne, jeśli wartością zmiennej jest kod JSON reprezentujący obiekt.
• message – wartość zmiennej przepływu client.ip z cudzysłowami.

&lt;Output&gt; element

Nazwa zmiennej, która przechowuje odpowiedź działania rozszerzenia.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

lub

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Po otrzymaniu odpowiedzi jej wartość jest umieszczana w określonej tutaj zmiennej, gdzie można uzyskać do niej dostęp z innego kodu serwera proxy interfejsu API.

Obiekty odpowiedzi rozszerzeń mają format JSON. Zasada obsługuje plik JSON na 2 sposoby:

• Przeanalizowane (domyślnie): zasada analizuje obiekt JSON i automatycznie generuje zmienne na podstawie danych JSON. Jeśli na przykład plik JSON zawiera ciąg "messageId" : 12345;, a zmienna wyjściowa nazywa się extensionOutput, w innych zasadach możesz uzyskać dostęp do identyfikatora wiadomości, używając zmiennej {extensionOutput.messageId}.
• Nieprzeanalizowano: zmienna wyjściowa zawiera nieprzetworzoną, nieprzetworzoną odpowiedź JSON z rozszerzenia. (możesz też przeanalizować wartość odpowiedzi w osobnym kroku, korzystając z zasad dotyczących JavaScriptu).

&lt;Output&gt; Atrybuty

Zmienne przepływu

Brak.

Kody błędów

Błędy zwracane przez zasady Apigee Edge mają spójny format opisany w Informacjach o błędach zasad.

W tej sekcji znajdziesz komunikaty o błędach i zmienne przepływu, które są ustawiane, gdy zasada powoduje błąd. Ta informacja jest ważna, gdy opracowujesz reguły awarii serwera proxy. Aby dowiedzieć się więcej, przeczytaj artykuły Błędy w zasadach i Jak postępować w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić, gdy wdrażasz serwer proxy zawierający tę zasadę.