Jak utworzyć objaśnienie w języku Java

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Co to jest wywołanie Javy?

Apigee Edge udostępnia szereg zasad, które spełniają typowe wymagania dotyczące zarządzania interfejsami API, takie jak bezpieczeństwo, przekształcanie danych, zarządzanie ruchem i inne.

W niektórych przypadkach interfejs API wymaga jednak niestandardowego zachowania, które nie jest zaimplementowane w standardowej zasadzie. W takich przypadkach Apigee udostępnia kilka opcji, które umożliwiają tworzenie skryptów lub kodu niestandardowego zachowania interfejsu API. Jednym ze sposobów jest zaimplementowanie żądanego zachowania w Javie.

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

Jak używać kodu Java w proxy?

Zasada wywołania Javy umożliwia wywoływanie kodu Java z poziomu wykonywanego przepływu proxy. Kod Java musi implementować określone interfejsy Java specyficzne dla Edge, które umożliwiają mu interakcję z wykonywanym proxy. Na przykład istnieją metody Java do pobierania i ustawiania nagłówków, parametrów zapytania , zmiennych przepływu i innych elementów w bieżącym kontekście przepływu proxy.

Kiedy należy używać wywołania Javy?

Przyjrzyjmy się sytuacjom, w których wywołania Javy są przydatne, oraz sytuacjom, w których warto rozważyć inne podejścia.

Najpierw rozważ alternatywne podejścia

Zanim użyjesz wywołania Javy, pamiętaj, że możesz zastosować inne podejścia zamiast. Na przykład:

  • W przypadku prostych operacji, takich jak wywołania interfejsu HTTP API do usług zdalnych, rozważ użycie zasady ServiceCallout. Zapoznaj się z zasadą Service Callout.
  • 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, możesz użyć języków JavaScript lub Python.

Co można zrobić w kodzie Java

Wywołanie Javy obsługuje te podstawowe operacje:

  • Sprawdzanie lub modyfikowanie wiadomości żądania lub odpowiedzi.
  • Pobieranie i ustawianie zmiennych przepływu. Do uzyskiwania dostępu do zmiennych przepływu Edge możesz używać metod Java. Jeśli chcesz uzyskać dostęp do informacji z mapy wartości kluczy (KVM), użyj zasady KVM, przypisz wartości KVM do zmiennych przepływu, a następnie możesz uzyskać dostęp do zmiennych przepływu z poziomu wywołania Javy.
  • Wywoływanie usług zewnętrznych.
  • Zgłaszanie błędów.
  • Modyfikowanie komunikatów o błędach i kodów stanu.

Czego nie można zrobić w kodzie Java

Większość wywołań systemowych jest niedozwolona. Nie możesz:

  • Odczytywać ani zapisywać wewnętrznego systemu plików. Oznacza to, że nie możesz używać żadnych pakietów Java do odczytywania i zapisywania w wewnętrznych systemach plików. Możesz jednak wykonywać zewnętrzne wywołania zdalne.
  • Uzyskiwać informacji o bieżącym procesie, liście procesów lub wykorzystaniu procesora i pamięci na maszynie.
  • Uzyskiwać dostępu do kodu źródłowego w plikach `expressions-1.0.0.jar` i `message-flow-1.0.0.jar`.

Chociaż niektóre z tych wywołań mogą działać, nie są one obsługiwane i w każdej chwili mogą zostać aktywnie wyłączone w. Unikaj wykonywania takich wywołań w kodzie.

Nie używaj bibliotek Java dołączonych do Apigee Edge ani nie polegaj na nich. Te biblioteki są przeznaczone tylko do funkcji Edge i nie ma gwarancji, że będą dostępne w kolejnych wersjach. Jeśli używasz takich bibliotek, używaj ich tylko w demonstracjach nieprodukcyjnych

Wywołanie Javy „Hello”

Przyjrzyjmy się podstawowemu przykładowi wywołania Javy „Hello World”. W tym przykładzie utworzymy proste proxy z wywołaniem Javy, które zwraca odpowiedź „Hello World”. Proxy może zwrócić jedną z 2 możliwych odpowiedzi:

  • Jeśli przekażesz nagłówek „username” z wartością „name”, proxy zwróci:

    Hello, <name>!
  • Jeśli pominiesz nagłówek, proxy zwróci tylko:

    "Hello, Guest!"

Pobierz projekt startowy

Aby uprościć sprawę, przygotowaliśmy dla Ciebie podstawowy projekt w GitHub w repozytorium Apigee api-platform-samples.

  1. Pobierz lub sklonuj api-platform-samples na swój komputer.
  2. W terminalu lub edytorze kodu wybierz projekt api-platform-samples/doc-samples/java-hello.

Napisz kod Java

  1. Otwórz plik źródłowy Java: java-hello/callout/src/main/java/HelloJava.java. Ten plik to szkielet głównej klasy Java, którą będziemy implementować. Importowane pakiety są wymagane w przypadku kodu wywołania Javy Edge. Te klasy udostępniają metody, które umożliwiają dostęp do kontekstu wykonywania proxy. Za chwilę omówimy kroki kompilowania i wdrażania tego kodu.
    package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
                
                try {

                        // Your code here.
            
            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}
  2. Zastąp zakomentowany wiersz // Your code here tym kodem:

    String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
  3. Zapisz plik.


Kompilowanie kodu za pomocą Maven

Projekt jest skonfigurowany tak, aby można go było skompilować za pomocą Maven. Jeśli chcesz użyć javac, po przykładzie Maven podamy przykład.

  1. Sprawdź, czy masz zainstalowany program Maven:

    mvn -version
  2. Uruchom skrypt java-hello/buildsetup.sh. Ten skrypt instaluje wymagane zależności JAR w lokalnym repozytorium Maven.
  3. Przejdź do katalogu java-hello/callout.
  4. Uruchom Maven:

    mvn clean package
  5. Jeśli chcesz, sprawdź, czy plik JAR edge-custom-policy-java-hello.jar został skopiowany do java-hello/apiproxy/resources/java. Jest to wymagana lokalizacja dla plików JAR, które chcesz wdrożyć za pomocą proxy.

Kompilowanie za pomocą javac (opcjonalnie)

W poprzedniej sekcji automatycznie wygenerujesz wymagany plik JAR Java za pomocą a polecenia Maven. Jeśli chcesz użyć javac do skompilowania kodu, możesz też wykonać podobne czynności (z katalogu java-hello ). Wymagane pliki JAR są dostępne w katalogu java-hello/lib.

  1. Przejdź do api-platform-samples/doc-samples/java-hello.
  2. Upewnij się, że masz javac w ścieżce.

    javac -version
  3. Uruchom to polecenie javac:

    javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java
     Spowoduje to utworzenie pliku com/apigeesample/HelloJava.class.
  4. Utwórz plik JAR zawierający skompilowaną klasę w katalogu apiproxy/resources/java. Jest to wymagana lokalizacja plików JAR , które chcesz wdrożyć za pomocą proxy. Możesz to zrobić, uruchamiając to polecenie w katalogu java-hello (nie zapomnij o kropce na końcu).

    jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .

Wdrażanie i wywoływanie proxy

W katalogu ./java-hello znajduje się skrypt wdrożenia. Zanim go uruchomisz, musisz przeprowadzić szybką konfigurację.

  1. Przejdź do api-platform-samples/doc-samples/java-hello.
  2. Jeśli jeszcze tego nie zrobisz, otwórz plik ../../setup/setenv.sh i edytuj go zgodnie z informacjami o koncie Apigee: nazwą użytkownika (adresem e-mail powiązanym z kontem), nazwą organizacji i domeną, której używasz do wywoływania interfejsów API. Na przykład w przypadku chmury Edge domena to https://api.enterprise.apigee.com. Jeśli jednak używasz Edge Private Cloud, domena może być inna.
  3. Zapisz plik setenv.sh.
  4. Uruchom skrypt wdrożenia:

    ./deploy.sh
  5. Jeśli wdrożenie się powiedzie, uruchom skrypt wywołania:

    ./invoke.sh

    Skrypt wywołania wywołuje polecenie cURL, które wygląda tak:

    curl  http://$org-$env.$api_domain/java-hello -H "username:Will"

    Zwraca „Hello, Will!

    Możesz edytować skrypt invoke.sh, aby zmienić nazwę. Jeśli zmienisz wywołanie cURL, aby usunąć nagłówek, polecenie zwróci "Hello, Guest!"

Informacje o proxy

Przyjrzyjmy się szybko zasadom używanym w tym proxy. Zwróć uwagę na to, gdzie zasady są umieszczone w przepływie proxy i dlaczego.

Zasada przypisywania wiadomości

Zasada przypisywania wiadomości jest dołączona do przepływu żądania ProxyEndpoint. Kopiuje ona nagłówek nazwy użytkownika z żądania i przypisuje go do odpowiedzi. Ta operacja umożliwia zasadzie wywołania Javy, która jest dołączona do przepływu odpowiedzi, dostęp do nagłówka nazwy użytkownika i tworzenie niestandardowej treści odpowiedzi na podstawie wartości tego nagłówka.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">     
    <DisplayName>CopyHeader</DisplayName>     
    <Copy source="request">         
        <Headers>             
          <Header name="username"/>         
        </Headers>     
    </Copy>     
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>     
    <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

Zasada wywołania Javy

Zasada wywołania Javy jest dołączona do przepływu odpowiedzi. Dzieje się tak, ponieważ niestandardowy kod Java wprowadza zmiany w nagłówkach i wiadomościach odpowiedzi. Element ClassName zasady określa główną klasę wykonywaną przez zasadę. Element ResourceURL to nazwa pliku JAR, który został utworzony i dodany do katalogu resources/java proxy.

<JavaCallout name="hello-java">         
    <ClassName>com.apigeesample.HelloJava</ClassName>         
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL> 
</JavaCallout>

Co musisz wiedzieć o wywołaniu Javy

Ważne informacje o implementowaniu wywołania Javy:

  • Importuje klasy z pakietów com.apigee.flow.execution i com.apigee.flow.message. Te pakiety muszą być zawarte w pliku JAR który jest spakowany i wdrożony. Plik JAR Java możesz przesłać za pomocą edytora proxy w interfejsie zarządzania lub dołączyć go do katalogu /resources/java w proxy interfejsu API, które tworzysz lokalnie.
  • Implementuje interfejs Execution. Każdy kod Java wykonywany w proxy interfejsu API musi implementować interfejs Execution.
  • Zasada wywołania Javy nie zawiera kodu. Zamiast tego odwołuje się do „zasobu” Java, który musisz spakować w pliku JAR.
  • Nazwy pakietów, których należy unikać: nie używaj nazw pakietów io.apigee ani com.apigee w wywołaniach Javy. Są one zarezerwowane i używane przez inne moduły Apigee.
  • Jeśli wywołanie Javy korzysta z dodatkowych bibliotek zewnętrznych spakowanych jako niezależne pliki JAR , umieść te pliki JAR również w katalogu /resources/java, aby mieć pewność, że zostaną prawidłowo wczytane w czasie działania.
  • Jeśli jest kilka plików JAR, po prostu dodaj je jako dodatkowe zasoby. Nie musisz modyfikować konfiguracji zasady, aby odwoływać się do dodatkowych plików JAR. Wystarczy umieścić je w /resources/java
  • Więcej informacji o przesyłaniu plików JAR Java znajdziesz w artykule Pliki zasobów.