Zasady dotyczące objaśnienia Java

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Co

Umożliwia używanie języka Java do wdrażania niestandardowych działań, które nie są domyślnie uwzględnione w zasadach Apigee. W kodzie Java możesz uzyskać dostęp do właściwości wiadomości (nagłówków, parametrów zapytania, treści) i zmiennych przepływu w przepływie proxy. Jeśli dopiero zaczynasz korzystać z tych zasad, zapoznaj się z artykułem Tworzenie wywołania Java.

Obsługiwane wersje Javy znajdziesz w artykule Obsługiwane oprogramowanie i wersje.

Kiedy

Wskazówki znajdziesz w sekcji „Kiedy należy używać wywołania Java?” w artykule Jak utworzyć wywołanie Java.

Informacje

Zasada wywołania Java umożliwia pobieranie i ustawianie zmiennych przepływu, wykonywanie niestandardowej logiki i obsługę błędów, wyodrębnianie danych z żądań lub odpowiedzi i nie tylko. Ta zasada umożliwia wdrożenie niestandardowego działania, które nie jest objęte żadnymi innymi standardowymi zasadami Edge.

Aplikację w języku Java możesz spakować z dowolnymi plikami JAR pakietu. Pamiętaj, że istnieją pewne ograniczenia dotyczące tego, co możesz zrobić za pomocą wywołania Java. Są one wymienione poniżej w sekcji Ograniczenia.

Przykłady

Prosty przykładPobieranie właściwości w kodzie JavaUstawianie zmiennych przepływu w kodzie Java
Jak utworzyć wywołanie Javy

Element <Property> zasady umożliwia określenie pary nazwa/wartość, którą można pobrać w czasie działania w kodzie Java. Działający przykład, który korzysta z właściwości, znajdziesz w artykule Jak używać właściwości w wywołaniu Java.

Użyj atrybutu name elementu <Property>, aby określić nazwę, za pomocą której można uzyskać dostęp do właściwości z kodu Java. Wartość elementu <Property> (wartość między tagiem otwierającym a zamykającym) to wartość, która zostanie odebrana przez kod Java. Wartość musi być ciągiem. Nie możesz odwoływać się do zmiennej przepływu, aby uzyskać wartość.

  • Skonfiguruj usługę. W tym przypadku wartością właściwości jest nazwa zmiennej response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • W kodzie Java zaimplementuj w klasie Execution ten konstruktor:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

Szczegółowy opis sposobu ustawiania zmiennych w kontekście wiadomości (zmiennych przepływu) w kodzie Java znajdziesz w tym poście na forum społeczności Apigee.

Odwołanie do elementu

Dokumentacja elementu opisuje elementy i atrybuty zasady JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Atrybuty elementu <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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

Atrybut Opis Domyślny Obecność
name

Wewnętrzna nazwa zasady. Wartość atrybutu name może zawierać litery, cyfry, spacje, łączniki, podkreślenia i kropki. Ta wartość nie może przekracza 255 znaków.

Opcjonalnie możesz użyć elementu <DisplayName> do oznaczenia zasady jako edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

 Nie dotyczy Wymagane
continueOnError

Ustaw jako false, aby w przypadku niepowodzenia zasady zwracany był błąd. To normalne w przypadku większości zasad.

Ustaw jako true, aby wykonywanie przepływu było kontynuowane nawet po zastosowaniu zasady niepowodzenie.

 fałsz Opcjonalnie
enabled

Aby egzekwować zasadę, ustaw wartość true.

Aby wyłączyć zasadę, ustaw wartość false. Te zasady nie będą jest wymuszane nawet wtedy, gdy jest ono połączone z przepływem.

 prawda Opcjonalnie
async

Ten atrybut został wycofany.

 fałsz Wycofano

&lt;DisplayName&gt; 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>
Domyślny

Nie dotyczy

Jeśli pominiesz ten element, atrybut name zasady otrzyma wartość .
Obecność Opcjonalnie
Typ Ciąg znaków

Element <ClassName>

Określa nazwę klasy Java, która jest wykonywana podczas działania zasad Java Callout. Klasa musi być zawarta w pliku JAR określonym przez <ResourceURL>. Zobacz też Jak utworzyć wywołanie Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Domyślnie: Nie dotyczy
Obecność: Wymagane
Typ: Ciąg znaków

Element <Property>

Określa właściwość, do której można uzyskać dostęp z kodu Java w czasie działania. W przypadku każdej właściwości musisz podać wartość literału ciągu znaków. W tym elemencie nie możesz odwoływać się do zmiennych przepływu. Działający przykład użycia właściwości znajdziesz w artykule Jak używać właściwości w wywołaniu Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Domyślnie: Brak
Obecność: Opcjonalny
Typ: Ciąg znaków

Atrybuty

Atrybut Opis Domyślny Obecność
nazwa

Określa nazwę usługi.

 Nie dotyczy Wymagane.

Element<ResourceURL>

Ten element określa plik JAR w języku Java, który będzie wykonywany po uruchomieniu zasady wywołania Java.

Możesz przechowywać ten plik w zakresie serwera proxy API (w /apiproxy/resources/java w pakiecie serwera proxy API lub w sekcji Skrypty w okienku Nawigator edytora serwera proxy API) albo w zakresie organizacji lub środowiska, aby można było go używać w wielu serwerach proxy API, zgodnie z opisem w artykule Pliki zasobów.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Domyślnie: Brak
Obecność: Wymagane
Typ: Ciąg znaków

Odniesienie do błędu

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

Błędy w czasie wykonywania

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

Kod błędu Stan HTTP Przyczyna Napraw
steps.javacallout.ExecutionError 500 Występuje, gdy kod w Javie zgłasza wyjątek lub zwraca wartość null podczas wykonywania zasady JavaCallout.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego zasadę.

Nazwa błędu Ciąg błędu Stan HTTP Występuje, gdy
ResourceDoesNotExist Resource with name [name] and type [type] does not exist Nie dotyczy Plik określony w elemencie <ResourceURL> nie istnieje.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] Nie dotyczy Pliku klasy określonego w elemencie <ClassName> nie ma w sekcji jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] Nie dotyczy Zobacz ciąg błędu. Zobacz też Obsługiwane oprogramowania i obsługiwanych wersji.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] Nie dotyczy Zobacz ciąg błędu.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] Nie dotyczy Zobacz ciąg błędu.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] Nie dotyczy Zobacz ciąg błędu.
NoResourceForURL Could not locate a resource with URL [string] Nie dotyczy Zobacz ciąg błędu.

Zmienne błędów

Te zmienne są ustawiane, gdy ta zasada wywołuje błąd. Więcej informacji znajdziesz w artykule Podstawowe informacje o błędach związanych z naruszeniem zasad.

Zmienne Gdzie Przykład
fault.name="fault_name" fault_name to nazwa błędu podana w tabeli Błędy czasu działania powyżej. Nazwa błędu to ostatnia część kodu błędu. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name to określona przez użytkownika nazwa zasady, która spowodowała błąd. javacallout.JC-GetUserData.failed = true

Przykładowa odpowiedź na błąd

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Przykładowa reguła błędu

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Schematy

Kompilowanie i wdrażanie

Szczegółowe informacje o kompilowaniu niestandardowego kodu Java i wdrażaniu go za pomocą serwera proxy znajdziesz w artykule Tworzenie wywołania Java.

Ograniczenia

Podczas pisania wywołań Java musisz pamiętać o tych ograniczeniach:

  • Większość wywołań systemowych jest niedozwolona. Nie możesz na przykład odczytywać ani zapisywać danych w wewnętrznym systemie plików.
  • Dostęp do sieci za pomocą gniazd. Apigee ogranicza dostęp do adresów sitelocal, anylocal, loopback i linklocal.
  • Wywołanie nie może uzyskać informacji o bieżącym procesie, liście procesów ani wykorzystaniu procesora lub pamięci na komputerze. Chociaż niektóre z tych połączeń mogą działać, nie są one obsługiwane i w każdej chwili mogą zostać aktywnie wyłączone. Aby zapewnić zgodność z przyszłymi wersjami, unikaj wywoływania takich funkcji w kodzie.
  • Korzystanie z bibliotek Java dołączonych do Apigee Edge nie jest obsługiwane. Te biblioteki są przeznaczone tylko do funkcji usługi Edge i nie ma gwarancji, że będą dostępne w kolejnych wersjach.
  • Nie używaj w objaśnieniach w języku Java nazw pakietów io.apigee ani com.apigee. Te nazwy są zarezerwowane i używane przez inne moduły Apigee.

Sposób prezentacji

Umieść plik JAR w proxy interfejsu API w folderze /resources/java. Jeśli wywołanie Java Callout korzysta z dodatkowych bibliotek innych firm spakowanych jako niezależne pliki JAR, umieść te pliki JAR również w katalogu /resources/java, aby mieć pewność, że zostaną prawidłowo załadowane w czasie działania.

Jeśli do tworzenia lub modyfikowania serwera proxy używasz interfejsu zarządzania, dodaj nowy zasób i określ dodatkowy zależny plik JAR. Jeśli jest kilka plików JAR, po prostu dodaj je jako dodatkowe zasoby. Nie musisz modyfikować konfiguracji zasad, aby odwoływać się do dodatkowych plików JAR. Wystarczy umieścić je w /resources/java.

Informacje o przesyłaniu plików JAR w Javie znajdziesz w sekcji Pliki zasobów.

Szczegółowy przykład pokazujący, jak spakować i wdrożyć wywołanie zwrotne w Javie za pomocą Mavena lub javac, znajdziesz w artykule Jak utworzyć wywołanie zwrotne w Javie.

Javadoc

Dokumentacja Javadoc dotycząca pisania kodu wywołania Java jest dostępna tutaj na GitHubie. Musisz sklonować lub pobrać HTML na swój system, a następnie otworzyć plik index.html w przeglądarce.

Zastosowanie

  • Zasada wywołania Java nie zawiera rzeczywistego kodu. Zamiast tego zasada Java Callout odwołuje się do „zasobu” Java i określa krok w przepływie interfejsu API, w którym wykonywany jest kod Java. Możesz przesłać plik JAR w języku Java za pomocą edytora proxy w interfejsie zarządzania lub dołączyć go do katalogu /resources/java w proxy interfejsu API, które tworzysz lokalnie.
  • W przypadku prostych operacji, takich jak wywołania interfejsu API do usług zdalnych, zalecamy używanie zasady ServiceCallout. Zapoznaj się z zasadami dotyczącymi objaśnień do usług.
  • W przypadku stosunkowo prostych interakcji z treścią wiadomości, takich jak modyfikowanie lub wyodrębnianie nagłówków HTTP, parametrów lub treści wiadomości, Apigee zaleca używanie zasady JavaScript.

Powiązane artykuły